Flexible Chat

Introduction

• Flexible Chat is a WordPress plugin that connects your website to an n8n-powered chat workflow. It allows you to create an AI-driven chat interface that can handle customer support, lead qualification, and automated conversations directly on your site.
• The plugin acts as a bridge between WordPress and your n8n workflow, sending user messages and metadata via webhook and receiving structured responses in real time.
• The plugin provides seamless integration with n8n chat workflows via webhook, allowing smooth communication between the chat interface and your automation processes.
• The chat UI is fully customizable — you can adjust colors, typography, and layout to match your brand and design preferences.
• It includes a welcome screen with predefined conversation topics, helping guide users from the very beginning.
• The system supports persistent chat history (optional), allowing conversations to be maintained across sessions if needed.
• AI responses are streamed in real time, providing an experience similar to ChatGPT with progressively appearing messages.
• It supports file uploads with MIME-type restrictions, giving you control over what types of files users can send.
• A built-in message feedback system (👍 / 👎) lets users quickly rate responses.
  You can attach custom metadata to every request, making it easier to pass additional context to your workflows.
• All text elements are fully localizable, giving you complete control over language and messaging.
• The chat window is fully responsive and includes a floating button, ensuring a smooth experience on both desktop and mobile devices.

Getting Started

Install the plugin files via the WordPress Plugins panel. After activation, you will find the settings panel in the WordPress sidebar under Settings > Flexible Chat.

The plugin settings menu consists of the following tabs:

• General
• Appearance
• Text Customization
• Advanced

Flexible Chat Settings

General

Webhook URL This field is required for the chat to function properly. It defines the endpoint where all chat messages are sent. Enter the full URL of your n8n chat webhook.
https://n8n.example.com/webhook/your-chat-id/chat

Chat Behavior

Show Welcome Screen Enable or disable the welcome screen before users start chatting. When enabled, users will see a greeting screen with instructions and optional conversation topics before starting the chat.

Conversation Topics

Allow users to select a topic before starting the conversation. This helps route requests to the appropriate workflow logic in n8n.

Message Title Displayed above the topic selection buttons. Leave empty to hide the heading.
Example: “What would you like to talk about?”

Message Text Optional helper text displayed below the title.
Example: “Pick a topic so we can route your conversation to the right person”.

Suggested Topics Add predefined conversation topics that users can select before sending their first message.

Appearance

Flexible Chat allows visual customization to match your website design.

Color Scheme

All colors are automatically processed to ensure accessibility and contrast compliance.

Primary Color Main brand color used for buttons, links, and interactive elements. Hover states are generated automatically.

Bot Message Background Background color for AI/bot messages. Text color is automatically adjusted for readability.

User Message Background Background color for user messages.

Chat Window Background Main background color of the chat window and message area.

Text Color Primary text color used for headers, titles, and important UI elements.

Typography

Base Font Size Controls the font size for chat messages and general UI text.

Border Radius Controls the roundness of chat bubbles and UI elements. Set to 0px for sharp corners.

Base Spacing Defines the global spacing unit used throughout the interface.

Message Padding Internal padding inside chat message bubbles.

Window Dimensions

Window Width Recommended range: 350px – 500px

Window Height Recommended range: 500px – 700px

Chat Button Size Controls floating button size when chat is closed.

Available options:

• Small
• Normal,
• Large

Text Customization

Customize all visible text in the chat interface.

Window Header Text

Chat Window Title: Main greeting displayed in the chat header.
Example: Hi there! 👋

Chat Window Subtitle: Secondary supporting text below the title.
Example: Start a chat. We're here to help you 24/7.

Chat Interaction Text

Input Field Placeholder: Placeholder text shown inside the message input field.
Example: Type your question...

Compliance Notice: Optional notice displayed under the input field.
Example: You are talking with AI. Avoid sharing confidential information.

Welcome Messages

Shown only if “Show Welcome Screen” is enabled.

Initial Bot Messages: Each line represents a separate message bubble:

Example: Hi there! 👋 How can we help you today?

Advanced

Chat Behavior

Persistent Chat History When enabled, chat history is stored in browser localStorage. Users can return to previous conversations across sessions. Note: This may affect privacy compliance depending on jurisdiction.

Streaming responses Enables real-time AI message streaming. Bot responses appear progressively as they are generated.

Requires:

• n8n workflow with streaming support
• Compatible AI nodes

Message Feedback Buttons Displays 👍 / 👎 buttons under bot responses. Requires n8n workflow support for feedback handling.

File Upload Configuration

Enable File Uploads Adds file upload button to chat interface. Files are sent directly to n8n workflow. Only enable if your workflow validates uploaded files properly.

Allowed File Types Defines which types of files can be uploaded in the chat. Use this option to specify and restrict uploads to selected file formats (e.g. images, PDFs, documents) for better control and security.

Example configurations:

• image/* – all images
• image/jpeg,image/png,image/gif – specific image formats
• application/pdf,application/msword – documents only
• image/*,application/pdf,text/* – Images, PDFs, and text files

Leave empty to allow all types (not recommended).

n8n Integration Settings

User Message Field Name Use this field to define under which key the user's input will be passed in the request payload. This should match the field expected by your n8n workflow (e.g. message, text, or user_input). Default: chatInput

Example payload:
{
"chatInput": "Hello, how can you help me?"
}

Session ID Field Name

The JSON field name that contains the unique session identifier for conversation tracking. Use this field to define under which key the session ID will be passed in the request payload. This allows your n8n workflow to recognize and maintain context for a specific user conversation across multiple messages (e.g. session_id, chat_id, or conversation_id). Default: sessionId

Example payload:
{
"sessionId": "abc123def456"
}

Used for tracking conversation continuity.

Custom Metadata

Send additional context data with every chat request. Must be valid JSON format. Use this field to include extra information in the request payload, such as user attributes, environment details, or custom flags. This data can be used by your n8n workflow to customize responses or control logic (e.g. {"user_role": "admin", "source": "website"}).
Send additional context with each request.

Example:
{
"user_id": 123,
"plan": "premium",
"source": "landing_page",
}
Use cases:

• User identification (user_id, email, account_type)
• Context tracking (current_page, referrer, UTM parameters)
• Business segmentation (subscription_plan, customer_tier)

Security & Best Practices

• Always validate incoming data in n8n workflows
• Restrict allowed file types in production
• Avoid storing sensitive data in localStorage unless necessary
• Use HTTPS webhook endpoints only
• Sanitize metadata before processing

Troubleshooting

Chat does not work

• Verify webhook URL is correct
• Ensure n8n workflow is active

No AI response

• Check workflow execution in n8n
• Validate output format

File upload not working

• Ensure file uploads are enabled
• Check MIME type restrictions

Streaming not working

• Confirm AI node supports streaming output
• Check workflow configuration