Live Chat

The Live Chat extension provides an embeddable chat widget that you can add to any website. Users interact with your AI agent directly on your site, with optional handoff to a human operator when needed.

Setup

1. Enable the extension

1. Navigate to your agent’s Extensions page.
2. In the Explore tab, find Live Chat under the Chat category.
3. Click the card to open the configuration page.

2. Customize the widget

The configuration page offers a live preview that updates in real time as you make changes.

Setting	Description
Title	The name displayed at the top of the chat widget (max 20 characters).
Theme	Visual theme for the widget. Choose from 6 options: Classic Auto, Dark, Classic Light, Classic Dark, Slate, or Brand A.
Welcome Message	The greeting shown when a user opens the chat (max 300 characters).
Suggested Questions	Quick-reply buttons to help users start a conversation without typing (up to 5, max 60 characters each).
Allowed Domains	Whitelist of domains where the widget is allowed to load (up to 10). The SynapsAI console domains are always included automatically.

3. Install on your website

After saving your configuration, click Show Code to reveal the integration snippet. Copy the generated HTML/JavaScript code and paste it into your website, just before the closing </body> tag:

<script>
  window.synapsaiConfig = {
    wsBase: "wss://api.synapsai.app",
    tenant: "your-tenant-id",
    agentKey: "your-agent-key",
    token: "your-token",
    title: "Support",
    theme: "classic-auto",
    // ... other options
  };
</script>
<script src="https://cdn.synapsai.app/chatweb/latest/synapsai-chatweb.min.js"></script>

The widget will appear as a floating chat bubble on your website.

Tip

You can also use a custom SDK URL if you’re self-hosting the widget. Replace the default CDN URL with your own.

Features

Live preview

The configuration page shows a real-time preview of your chat widget. As you change the title, theme, welcome message, or suggested questions, the preview updates immediately so you can see exactly how it will look on your website.

On desktop, the preview appears side-by-side with the form. On mobile, you can switch between Edit and Preview tabs.

Suggested questions

Suggested questions appear as clickable buttons when the chat opens. They help users start a conversation quickly without having to type. For example:

• “What are your business hours?”
• “I’d like to know about pricing”
• “How can I contact support?”

You can add up to 5 suggestions, each with a maximum of 60 characters.

Domain whitelisting

For security, you can restrict which domains are allowed to load the widget. Only websites on your allowed list will be able to embed the chat. The SynapsAI console domains (console.synapsai.app, admin.synapsai.app) are always allowed automatically.

Themes

Choose from 6 pre-built themes to match your website’s design:

Theme	Description
Classic Auto	Adapts to the user’s system preference (light or dark).
Dark	Dark background with light text.
Classic Light	Clean white background.
Classic Dark	Dark background with classic styling.
Slate	Neutral gray tones.
Brand A	Branded styling with accent colors.

How it works

1. A user visits your website and clicks the chat bubble.
2. The widget connects to SynapsAI via WebSocket for real-time messaging.
3. The AI agent processes messages using your knowledge base, FAQ, and system prompt.
4. Responses appear instantly in the chat widget.
5. If configured, the agent can hand off to a human operator when needed.

Multi-tab support

The widget uses leader election to maintain a single WebSocket connection across multiple browser tabs. If a user has your website open in several tabs, only one tab maintains the connection — the others sync automatically. This prevents duplicate messages and reduces server load.

Troubleshooting

Problem	Solution
Widget not appearing	Check that the script is loaded before </body>. Verify the domain is in your allowed list.
”Connection failed”	Ensure your agent is active and the token in the config is valid. Check browser console for WebSocket errors.
Wrong theme showing	Clear browser cache or hard-refresh the page. The theme is loaded from the config at widget initialization.
Widget appears on unwanted pages	Add only specific page domains to the allowed list, or control the script inclusion on your website side.

Next steps

• Configure behavior — customize how your agent responds in the chat widget.
• Operator Handoff — set up human takeover for complex conversations.
• WhatsApp — add WhatsApp as another channel alongside web chat.
• Conversations — review Live Chat conversation history.