diff --git a/fern/docs.yml b/fern/docs.yml index bdc3e592..e629bd9d 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -335,6 +335,8 @@ navigation: path: pages/06-integrations/zapier.mdx - page: Make path: pages/06-integrations/make.mdx + - page: n8n + path: pages/06-integrations/n8n.mdx - page: Postman path: pages/06-integrations/postman.mdx - section: Meeting transcriber tools diff --git a/fern/pages/06-integrations/index.mdx b/fern/pages/06-integrations/index.mdx index 69d20937..99cec92f 100644 --- a/fern/pages/06-integrations/index.mdx +++ b/fern/pages/06-integrations/index.mdx @@ -52,11 +52,18 @@ AssemblyAI seamlessly integrates with a variety of tools and platforms to enhanc Build complex automation scenarios with Make's visual workflow builder. - Test and explore AssemblyAI's APIs using Postman collections. + Automate workflows with n8n's fair-code automation platform and integrate AssemblyAI. + + + Create automated workflows with this open-source alternative to Zapier. diff --git a/fern/pages/06-integrations/n8n.mdx b/fern/pages/06-integrations/n8n.mdx new file mode 100644 index 00000000..5a5c9b55 --- /dev/null +++ b/fern/pages/06-integrations/n8n.mdx @@ -0,0 +1,429 @@ +--- +title: "n8n Integration with AssemblyAI" +description: "Integrate AssemblyAI with 1000+ apps and services using n8n's automation platform." +hide-nav-links: true +--- + +Unlock the full potential of AssemblyAI and [n8n's](https://n8n.io/) automation platform by connecting AssemblyAI's speech-to-text and audio intelligence capabilities with over 1,000 apps, data sources, services, and n8n's built-in AI features. + +Use n8n's pre-authenticated HTTP Request node to create powerful automations with AssemblyAI, giving you the flexibility to build workflows on any stack. The AssemblyAI integration is built and maintained by AssemblyAI and verified by n8n. + +n8n offers both a cloud-hosted version and a self-hosted option, giving you flexibility in how you deploy your automations. + +## Prerequisites + +Before you begin, you'll need: + +- An [AssemblyAI API key](https://www.assemblyai.com/app/api-keys) +- An n8n account (either [n8n Cloud](https://app.n8n.cloud/register) or a self-hosted instance) + +## Popular Integration Pairings + +AssemblyAI works seamlessly with n8n's most popular nodes, enabling you to build powerful automation workflows: + +- **Google Sheets** - Store transcripts and analysis results in spreadsheets +- **Gmail** - Send transcription results via email +- **Slack** - Post transcripts to channels or send direct messages +- **OpenAI** - Combine transcription with AI analysis and summarization +- **Google Drive** - Automatically transcribe audio files from cloud storage +- **Notion** - Save transcripts to your knowledge base +- **Airtable** - Organize transcription data in databases +- **Discord** - Share transcripts in Discord channels +- **Telegram** - Send transcription results via Telegram bots + +## Complete Workflow Tutorial + +This comprehensive tutorial walks you through building a complete AssemblyAI workflow in n8n that: +1. Uploads an audio file to AssemblyAI +2. Submits a transcription request with advanced features +3. Polls for completion +4. Processes the transcript output +5. Retrieves additional data (redacted audio, sentences) +6. Cleans up by deleting the transcript + +### Step 1: Upload Audio File + +The first step is to upload your audio file to AssemblyAI. You have several options depending on where your audio file is located. + +#### Option A: Upload Local File + +If you have a local audio file, use an HTTP Request node to upload it to AssemblyAI: + +1. Add an **HTTP Request** node to your workflow +2. Configure the node: + - **Method**: `POST` + - **URL**: `https://api.assemblyai.com/v2/upload` + - **Authentication**: Select **Generic Credential Type** → **Header Auth** + - **Name**: `authorization` + - **Value**: Your AssemblyAI API key + - **Body**: Select **Binary File** + - **Input Binary Field**: Select the field containing your audio file data + +The response will contain an `upload_url` that you'll use in the next step. + +#### Option B: Use Remote File URL + +If your audio file is already hosted online (e.g., on a CDN, S3, or public URL), you can skip the upload step and use the URL directly in Step 2. + +#### Option C: Get File from Google Drive + +To transcribe files from Google Drive: + +1. Add a **Google Drive** trigger node or **Google Drive** node +2. Configure it to: + - **Operation**: Download a file + - **File ID**: The ID of the audio file you want to transcribe +3. Connect this to the upload HTTP Request node from Option A + +The Google Drive node will output the file as binary data, which the upload node will send to AssemblyAI. + +### Step 2: Submit Transcription Request + +Now submit the transcription request with your desired features enabled. + +1. Add an **HTTP Request** node +2. Configure the node: + - **Method**: `POST` + - **URL**: `https://api.assemblyai.com/v2/transcript` + - **Authentication**: Use the same **Header Auth** credential from Step 1 + - **Body**: Select **JSON** + - **JSON Body**: + +```json +{ + "audio_url": "{{$node['HTTP Request'].json['upload_url']}}", + "speaker_labels": true, + "language_detection": true, + "sentiment_analysis": true, + "entity_detection": true, + "auto_chapters": true +} +``` + +If you're using a remote file URL (Option B), replace the `audio_url` value with your file URL. + +#### Available Features + +You can enable any combination of these features in your transcription request: + +- **speaker_labels**: Identify different speakers (diarization) +- **language_detection**: Automatically detect the language +- **sentiment_analysis**: Analyze sentiment of each sentence +- **entity_detection**: Extract names, organizations, locations +- **auto_chapters**: Automatically segment into chapters +- **auto_highlights**: Extract key highlights +- **content_safety**: Detect sensitive content +- **iab_categories**: Categorize content by IAB taxonomy +- **summarization**: Generate a summary (requires model parameter) +- **redact_pii**: Redact personally identifiable information +- **redact_pii_audio**: Generate redacted audio file +- **redact_pii_policies**: Specify which PII types to redact + +The response will contain a `transcript_id` that you'll use to poll for completion. + +### Step 3: Poll for Transcription Completion + +Since transcription is asynchronous, you need to poll the API until the transcript is ready. + +1. Add a **Loop** node after the transcription request +2. Inside the loop, add an **HTTP Request** node: + - **Method**: `GET` + - **URL**: `https://api.assemblyai.com/v2/transcript/{{$node['HTTP Request 1'].json['id']}}` + - **Authentication**: Use the same **Header Auth** credential + +3. Add an **IF** node to check the status: + - **Condition**: `{{$json['status']}}` equals `completed` or `error` + - **True branch**: Exit the loop (transcript is ready) + - **False branch**: Continue polling + +4. On the False branch, add a **Wait** node: + - **Wait Time**: 5 seconds + - Connect back to the HTTP Request node to poll again + +5. Configure the Loop node: + - **Max Iterations**: 100 (to prevent infinite loops) + +When the transcript is complete, the response will contain the full transcript data including: +- `text`: The complete transcription +- `words`: Array of individual words with timestamps +- `utterances`: Array of speaker utterances (if speaker_labels enabled) +- `sentiment_analysis_results`: Sentiment data (if enabled) +- `entities`: Detected entities (if enabled) +- `chapters`: Auto-generated chapters (if enabled) + +### Step 4: Process Transcript Output + +Now that you have the completed transcript, you can process it and send it to other services. + +#### Create Human-Readable Transcript + +To format the transcript into a readable format: + +1. Add a **Code** node (JavaScript or Python) +2. Use this code to format utterances into a readable transcript: + +**JavaScript:** +```javascript +const transcript = $input.item.json; +let formattedText = ''; + +if (transcript.utterances) { + // Format with speaker labels + for (const utterance of transcript.utterances) { + formattedText += `Speaker ${utterance.speaker}: ${utterance.text}\n\n`; + } +} else { + // Use plain text if no speaker labels + formattedText = transcript.text; +} + +return { formattedText }; +``` + +**Python:** +```python +transcript = _input.item.json +formatted_text = '' + +if 'utterances' in transcript and transcript['utterances']: + # Format with speaker labels + for utterance in transcript['utterances']: + formatted_text += f"Speaker {utterance['speaker']}: {utterance['text']}\n\n" +else: + # Use plain text if no speaker labels + formatted_text = transcript['text'] + +return {'formattedText': formatted_text} +``` + +#### Save to Google Sheets + +To save the transcript to Google Sheets: + +1. Add a **Google Sheets** node +2. Configure it: + - **Operation**: Append or Update + - **Document**: Select your spreadsheet + - **Sheet**: Select the sheet name + - **Columns**: Map the data: + - Column A: `{{$node['HTTP Request 2'].json['id']}}` (Transcript ID) + - Column B: `{{$node['Code'].json['formattedText']}}` (Formatted transcript) + - Column C: `{{$node['HTTP Request 2'].json['audio_duration']}}` (Duration) + - Column D: `{{new Date().toISOString()}}` (Timestamp) + +#### Send via Email + +To email the transcript: + +1. Add a **Gmail** or **Send Email** node +2. Configure it: + - **To**: Recipient email address + - **Subject**: `Transcript Ready: {{$node['HTTP Request 2'].json['id']}}` + - **Body**: `{{$node['Code'].json['formattedText']}}` + +#### Post to Slack + +To post the transcript to Slack: + +1. Add a **Slack** node +2. Configure it: + - **Operation**: Send Message + - **Channel**: Select your channel + - **Text**: `New transcript completed:\n\n{{$node['Code'].json['formattedText']}}` + +### Step 5: Retrieve Additional Data + +AssemblyAI provides additional endpoints to retrieve more data from your completed transcript. + +#### Get Redacted Audio + +If you enabled `redact_pii_audio` in your transcription request, you can retrieve the redacted audio file: + +1. Add an **HTTP Request** node +2. Configure it: + - **Method**: `GET` + - **URL**: `https://api.assemblyai.com/v2/transcript/{{$node['HTTP Request 2'].json['id']}}/redacted-audio` + - **Authentication**: Use the same **Header Auth** credential + - **Response Format**: Binary + +The response will contain the redacted audio file with PII removed. + +#### Get Sentences + +To retrieve the transcript broken down by sentences: + +1. Add an **HTTP Request** node +2. Configure it: + - **Method**: `GET` + - **URL**: `https://api.assemblyai.com/v2/transcript/{{$node['HTTP Request 2'].json['id']}}/sentences` + - **Authentication**: Use the same **Header Auth** credential + +The response will contain an array of sentences with: +- `text`: The sentence text +- `start`: Start time in milliseconds +- `end`: End time in milliseconds +- `confidence`: Confidence score +- `speaker`: Speaker label (if speaker_labels enabled) + +#### Get Paragraphs + +To retrieve the transcript broken down by paragraphs: + +1. Add an **HTTP Request** node +2. Configure it: + - **Method**: `GET` + - **URL**: `https://api.assemblyai.com/v2/transcript/{{$node['HTTP Request 2'].json['id']}}/paragraphs` + - **Authentication**: Use the same **Header Auth** credential + +### Step 6: Delete Transcript + +Once you're done processing the transcript, you can delete it from AssemblyAI to clean up: + +1. Add an **HTTP Request** node at the end of your workflow +2. Configure it: + - **Method**: `DELETE` + - **URL**: `https://api.assemblyai.com/v2/transcript/{{$node['HTTP Request 2'].json['id']}}` + - **Authentication**: Use the same **Header Auth** credential + +The transcript will be permanently deleted from AssemblyAI's servers. + +## Alternative: Using Webhooks + +Instead of polling for completion, you can use webhooks for a more efficient approach: + +1. Add a **Webhook** node to your workflow +2. Set it to **Production** mode and copy the webhook URL +3. In your transcription request (Step 2), add the webhook URL: + +```json +{ + "audio_url": "{{$node['HTTP Request'].json['upload_url']}}", + "webhook_url": "https://your-n8n-instance.com/webhook/your-webhook-id", + "speaker_labels": true +} +``` + +When the transcription is complete, AssemblyAI will send a POST request to your webhook with the transcript status. You can then retrieve the full transcript using the transcript ID from the webhook payload. + +## Error Handling + +Add error handling to your workflow to manage failures gracefully: + +1. After the polling loop, add an **IF** node to check for errors: + - **Condition**: `{{$json['status']}}` equals `error` + +2. On the True branch (error case): + - Add a **Slack** or **Email** node to send an error notification + - Include the error message: `{{$json['error']}}` + +3. On the False branch (success case): + - Continue with the normal workflow + +## Example Workflow JSON + +Here's a complete workflow JSON that you can import into n8n: + +```json +{ + "name": "AssemblyAI Complete Workflow", + "nodes": [ + { + "parameters": {}, + "name": "Start", + "type": "n8n-nodes-base.start", + "position": [250, 300] + }, + { + "parameters": { + "method": "POST", + "url": "https://api.assemblyai.com/v2/upload", + "authentication": "genericCredentialType", + "genericAuthType": "httpHeaderAuth", + "sendBody": true, + "bodyContentType": "raw", + "rawContentType": "application/octet-stream" + }, + "name": "Upload Audio", + "type": "n8n-nodes-base.httpRequest", + "position": [450, 300] + }, + { + "parameters": { + "method": "POST", + "url": "https://api.assemblyai.com/v2/transcript", + "authentication": "genericCredentialType", + "genericAuthType": "httpHeaderAuth", + "sendBody": true, + "bodyContentType": "json", + "jsonBody": "{\n \"audio_url\": \"{{$json['upload_url']}}\",\n \"speaker_labels\": true,\n \"language_detection\": true\n}" + }, + "name": "Submit Transcription", + "type": "n8n-nodes-base.httpRequest", + "position": [650, 300] + }, + { + "parameters": { + "method": "GET", + "url": "https://api.assemblyai.com/v2/transcript/{{$node['Submit Transcription'].json['id']}}", + "authentication": "genericCredentialType", + "genericAuthType": "httpHeaderAuth" + }, + "name": "Check Status", + "type": "n8n-nodes-base.httpRequest", + "position": [850, 300] + }, + { + "parameters": { + "method": "DELETE", + "url": "https://api.assemblyai.com/v2/transcript/{{$node['Check Status'].json['id']}}", + "authentication": "genericCredentialType", + "genericAuthType": "httpHeaderAuth" + }, + "name": "Delete Transcript", + "type": "n8n-nodes-base.httpRequest", + "position": [1250, 300] + } + ], + "connections": { + "Start": { + "main": [[{"node": "Upload Audio", "type": "main", "index": 0}]] + }, + "Upload Audio": { + "main": [[{"node": "Submit Transcription", "type": "main", "index": 0}]] + }, + "Submit Transcription": { + "main": [[{"node": "Check Status", "type": "main", "index": 0}]] + }, + "Check Status": { + "main": [[{"node": "Delete Transcript", "type": "main", "index": 0}]] + } + } +} +``` + +This is a simplified version. You'll need to add the polling loop, error handling, and output processing nodes as described in the tutorial above + +## Additional Resources + +- [n8n AssemblyAI Integration Page](https://n8n.io/integrations/assemblyai/) +- [n8n HTTP Request Node Documentation](https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.httprequest/) +- [AssemblyAI API Reference](/api-reference) +- [n8n Workflow Templates](https://n8n.io/workflows/) + +## Example Use Cases + +### Meeting Transcription Pipeline + +Automatically transcribe meeting recordings uploaded to cloud storage, extract action items using sentiment analysis and entity detection, and send summaries to team members. + +### Podcast Processing + +Transcribe podcast episodes, generate chapters automatically, create searchable transcripts, and publish them to your CMS. + +### Customer Support Analysis + +Transcribe support calls, analyze sentiment, detect PII for compliance, and store insights in your CRM or database. + +### Content Moderation + +Transcribe user-generated audio content, use content moderation to flag inappropriate content, and automatically filter or review flagged items.