Web Chat
Create and customize web chat widgets for your website, get the embed code, and supervise the resulting AI conversations.
Objective
Add an AI chat widget to your website. From the Web Chat module you create and customize one or more widgets, copy the embed snippet for your site, and hand each widget to an AI agent. Visitor conversations are then supervised in the shared inbox, where you can take over from the AI, reply, and close them.
Access
Sidebar -> Messaging -> Web Chat Routes:
- /app/{tenant}/webchat (create and manage widgets, get embed code)
- /app/{tenant}/conversations?channel=web_chat (Web Chat conversations in the unified inbox)
- /app/{tenant}/conversations/{id} (a single conversation)
The View conversations button on the Web Chat page opens the unified inbox filtered to Web Chat. Widget management lives on this page; the conversations themselves live in the shared inbox, not here.
Roles
- owner, admin, agent
- Deleting a conversation is restricted to owner and admin.
Prerequisites
- At least one active agent with the Web Chat channel enabled (configured in the Agents module). Without one, the create flow prompts you to set one up first.
- A verified email. An unverified workspace cannot create a widget.
- Your plan's web chat widget allowance. New workspaces include one widget; more require a higher plan.
Create a widget
- On the Web Chat page, click Create Widget (or the Create Your First Widget card).
- Fill in the create modal (Create Web Chat Widget). A Live Preview at the top reflects your changes as you type.
- Click Create Widget to save.
| Field | Notes |
|---|---|
| Widget Name | Required. Internal name to identify this widget; not shown to visitors. |
| AI Agent | Required. Must be an active agent with the Web Chat channel enabled. Choose a solo agent ("Agents (answer alone)") or a Team ("Teams (can ask a specialist for help)"). |
| Language | Widget language shown to visitors: English, Spanish, Portuguese, French, or German. |
| Widget Title | Header text visitors see. Default "Chat with us". |
| Welcome Message | First message shown when the chat opens. Default "How can we help you today?". |
| Primary Color | Accent color, from presets or a custom hex value. Default #3b82f6. |
| Position | Bottom Right or Bottom Left. |
| Widget Theme | Light, Dark, or Auto. Auto follows the visitor's system preference. |
| Chat button icon | Floating button icon: Chat, Message, Support, Spark, Wave, or Helios. |
| Animate chat button | Adds a gentle bounce to attract attention. Default ON. |
| Widget Avatar | Custom logo or avatar (PNG, JPG, SVG, or WebP; max 2MB). |
| Allowed Domains | Restrict the widget to specific domains. Accepts example.com, *.example.com, and localhost:3000. Leave empty to allow any site. |
| Collect visitor name | Ask the visitor for a name before starting the chat. |
| Collect visitor email | Ask the visitor for an email before starting the chat. |
| Show branding | Display "Powered by HeliosVision". Turning it off requires the Growth, Business, or Enterprise plan. |
| Offline Message | Optional message shown when agents are unavailable. |
Notes:
- Team mode is only available when your plan includes Teams and the chosen agent is a coordinator with at least one approved specialist. Otherwise the widget answers with a solo agent.
- If a widget's linked agent later becomes inactive or loses the Web Chat channel, the editor flags it and asks you to pick an active agent before saving.
Manage widgets
Each widget appears as a card showing its name, linked agent, an Active / Inactive badge, and a preview of its title, position, color, and language. Card actions:
- Get Embed Code — open the install snippets (see below).
- Edit — reopen the same modal titled "Edit Widget".
- The actions menu (⋮) adds Delete Widget.
When you have more than one widget, a Search box and a Sort control (Name A–Z, Name Z–A, Active first) appear above the grid.
Deleting a widget asks you to confirm. Existing conversations are preserved, but new visitors can no longer start chats with that widget.
Get the embed code
Open Get Embed Code on any widget to copy an install snippet. The modal offers three paths:
| Option | Use it when |
|---|---|
| Install with your AI coding agent | You build with Cursor, Claude Code, v0, Lovable, or similar. Copy the prompt and paste it into your agent; it wires the widget into your framework for you. |
| Basic Installation | You paste the script into your site's HTML yourself, just before the closing </body> tag. |
| With Visitor Identification | Same as Basic, plus optional fields to pre-identify visitors (name, email, and custom metadata). |
Each snippet already contains your widget's ID and always points at the production URL, so it works from any site. After pasting the snippet and deploying, the floating chat button appears on your pages.
You can also drive the widget from JavaScript:
window.HeliosChat.api.open()opens the chat.window.HeliosChat.api.close()closes the chat.window.HeliosChat.api.sendMessage('Hi')sends a message.
Plan limits and branding
- The number of widgets you can create depends on your plan. Reaching the limit opens an upgrade dialog instead of the create form.
- Removing "Powered by HeliosVision" branding requires the Growth, Business, or Enterprise plan. On other plans the toggle stays on.
Conversations
Web Chat conversations are supervised in the shared inbox. Open a conversation to see the visitor's name and email (or "Anonymous Visitor" when neither was collected), the message thread, and the controls below.
| Control | What it does |
|---|---|
| AI Active / AI Disabled | Turn the agent's automatic replies on or off for this conversation. |
| Take Over | Shown when the AI asks for help ("AI Requested Assistance"). Takes over and pauses AI replies. |
| Return to AI | Hand a human-handled conversation back to the AI. |
| Close / Reopen | Change the status between Active and Closed. |
| Archive | Hide a closed conversation from the active list; it can be reopened later. |
| Delete | Permanently delete the conversation and its messages (owner and admin only). |
| Generate Insights | Produce an AI summary and sentiment analysis for the conversation. |
Notes:
- The panel refreshes automatically every few seconds; your reply appears immediately as you send it.
- A message bubble is marked RAG when the agent used your documents and SQL when it queried your data tables.
- Inbound attachments render inline: images as thumbnails, voice notes and documents as labeled chips.
- Generate Insights uses AI. If your workspace relies on your own OpenAI key and it is missing or invalid, you are prompted to add or fix it under Settings -> API Keys.
- These conversations also appear in the full unified inbox alongside every other channel.
Good practices
- Set up an agent with the Web Chat channel before creating a widget, so the widget has someone to answer.
- Use Allowed Domains to keep a widget from loading on sites you do not control.
- Turn on Collect visitor email when you want a way to follow up after the chat.
- Take over from the AI when a conversation escalates, then hand it back once resolved.
Common notes
- If a widget shows the "previously linked agent is inactive" warning, activate the agent (or enable its Web Chat channel) in the Agents module, then reassign it.
- Deleting a widget does not delete past conversations; it only stops new chats.
- Branding and widget-count limits are enforced by your plan; upgrade to lift them.