N8N Chat UI
Docs
Media Attachments

Media Attachments

Learn how to render media content as bot responses in your chat widgets using the attachments response format.

Widgets built with N8N Chat UI support rendering various types of media attachments as bot responses directly in the chat interface. This guide covers how to structure your backend responses to include media content that will be displayed when your bot responds to user messages.

Response Format

To include media attachments in your bot responses, add an attachments array to your JSON response:

{
  "output": "Here's the media content you requested",
  "attachments": [
    {
      "type": "data_url",
      "data": "data:audio/mp3;base64,SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4Ljc2LjEwMAAA",
      "mimeType": "audio/mp3"
    }
  ]
}

The attachments field is optional and extends the standard response format used by all N8N Chat UI widgets.

Attachment Structure

Each attachment object in the attachments array supports the following fields:

Required Fields

  • type - The type of attachment data. Supports:
    • "url" - For external URLs pointing to media files
    • "data_url" - For base64-encoded media data
  • data - The actual media content:
    • For type: "url": A direct URL to the media file
    • For type: "data_url": A base64-encoded data URI
  • mimeType - The MIME type of the media file (e.g., "audio/mp3")

Supported Media Types

Audio

Currently, the chat widget supports various audio formats for playback directly within the chat interface.

Supported Audio Formats

  • MP3 - audio/mp3 or audio/mpeg
  • WAV - audio/wav
  • OGG - audio/ogg
  • WebM Audio - audio/webm

Audio-Specific Optional Field

  • autoPlayAudio - A boolean field that controls whether the audio should automatically start playing when the response is received. Defaults to false if not specified. When multiple audio files have autoPlayAudio: true, only the first audio file will auto-play.

Audio from URL

{
  "output": "Here's your requested audio:", // Use "" to show only audio without text
  "attachments": [
    {
      "type": "url",
      "data": "https://example.com/audio/sample.mp3",
      "mimeType": "audio/mp3",
      "autoPlayAudio": true
    }
  ]
}

Audio from Base64 Data

{
  "output": "Playing generated audio:", // Use "" to show only audio without text
  "attachments": [
    {
      "type": "data_url",
      "data": "data:audio/wav;base64,UklGRnoGAABXQVZFZm10IBAAAAABAAEA",
      "mimeType": "audio/wav",
      "autoPlayAudio": false
    }
  ]
}

Multiple Audio Files

You can include multiple audio files in a single response:

{
  "output": "Here are multiple audio files:", // Use "" to show only audio without text
  "attachments": [
    {
      "type": "url",
      "data": "https://example.com/intro.mp3",
      "mimeType": "audio/mp3",
      "autoPlayAudio": true
    },
    {
      "type": "data_url",
      "data": "data:audio/wav;base64,UklGRnoGAABXQVZFZm10IBAAAAABAAEA",
      "mimeType": "audio/wav",
      "autoPlayAudio": true
    }
  ]
}

Note: In the above example, only the first audio file (intro.mp3) will auto-play since both have autoPlayAudio: true.

Best Practices

File Size Considerations

  • URL-based attachments: Recommended for larger files as they don't increase response payload size
  • Base64 data: Best for smaller files (< 1MB) or dynamically generated content
  • Storage considerations: Chat history (including attachments) is stored in browser local storage, which has a 5-10MB limit per website. URL-based attachments only store the reference and are recommended, while base64 data stores the entire content and can quickly consume storage limits, potentially causing data loss. Avoid using base64 for large files.

Video Tutorial

For a comprehensive guide on implementing bi-directional voice chat using media attachments, including setup, workflow configuration, and best practices, watch the detailed YouTube video below:

This video covers:

  • How to set up bi-directional voice chat using media attachments
  • Best practices for handling audio responses in your chat widget
  • Workflow configuration for voice-enabled interactions
  • Real-world implementation examples

You'll also find downloadable workflow templates and additional resources in the video description.

Related Configuration

Enhance your media-enabled chat widget with:

Summary

  • Use the attachments array to include media content in bot responses
  • Support both URL-based and base64-encoded media formats
  • Currently supports various audio formats
  • Choose between URLs and data URIs based on file size and storage considerations
  • Consider local storage limitations when using base64 data
Custom CSSEvent Callbacks