Backend Integration

Widgets built with N8N Chat UI can be directly connected to n8n workflows or any custom backend that implements the required response format. This guide covers the response structure and setup instructions for both approaches.

Response Format

Your backend (whether n8n or custom) must return a JSON object with the following structure:

{
  "output": "Your response text to render"
}

Note for n8n users: If you encounter an "Unexpected end of JSON input" error, you need to JSON stringify your response before sending it. This is a common issue that occurs because the chat widget expects properly formatted text data in the response. When your dynamic output contains double quotes or special characters and you try to wrap it again with quotes manually, it can cause JSON parsing errors.

Using JSON.stringify() properly escapes any quotes and special characters in your content. Here's exactly how your response body should look in n8n's Respond to Webhook node:

{
  "output": {{ JSON.stringify($json.output) }}
}

Copy

Important: Do not wrap the {{ JSON.stringify(...) }} expressions with quotes, as the JSON.stringify() function already handles the proper quoting and escaping of the content. The expression should be used exactly as shown above in the Respond to Webhook node's Response Body field.

Required Fields

• output - The text you want displayed in the chat window. Supports both plain text and rich formatting with Markdown & HTML. Learn more about formatting options.

Optional Fields

• followUpPrompts - An array of predefined messages or questions that appear as clickable buttons below the chat response. When a user clicks one of these suggestions, it's automatically sent as their next message.

{
  // other fields...
  "followUpPrompts": ["Track my order", "I need help", "Cancel order"]
}

• attachments - Render media files alongside the text response. Learn more about media attachments.

Integration Options

1. Using n8n

N8N Chat UI widgets is designed to work seamlessly with n8n workflows. To get started:

1. Create a new n8n workflow
2. Add a Chat Trigger or Webhook node as your trigger
3. Configure your chat processing logic
4. Ensure your final node returns the response in the format shown above

2. Using Custom Backend

For cases where you need to use your own backend, you can connect the chat widget to any custom API endpoint:

1. Set up an endpoint that accepts POST requests
2. Configure your endpoint to process the incoming chat messages
3. Return responses in the required JSON format
4. Ensure your endpoint responds with a 200 OK status

Enhanced Features

Consider these additional capabilities to create a more engaging chat experience:

• Use metadata to pass contextual information from your website to your backend
• Enable file uploads to allow users to share documents and images
• Add voice input capabilities for a more interactive interface
• Include media attachments to render different types of media content
• Programmatically control your widget using the Chat Widget Controls API

Summary

• Always return a JSON object with at least the output field
• Optionally include followUpPrompts for interactive suggestions
• The widget supports both n8n workflows and custom backends
• Ensure your endpoint responds with valid JSON and a 200 OK status
• For advanced formatting options, check out our guide on rendering Markdown and HTML