Web Chat Widget (Embed)

Objective

Add an AI chat widget to your website. From the Web Chat module you create one or more widgets, customize how each one looks and behaves, link it to an AI agent, and copy an install snippet to embed on your site. Visitor conversations are then supervised in the shared inbox.

Access

Sidebar -> Messaging -> Web Chat Routes:

• /app/{tenant}/webchat (create, customize, and manage widgets; get the embed code)
• /app/{tenant}/conversations?channel=web_chat (Web Chat conversations, reached from the View conversations button)

Widget management lives on this page. The conversations themselves live in the shared inbox, not here.

Roles

• owner, admin, agent

Prerequisites

• A verified email. An unverified workspace cannot create or edit a widget.
• At least one active agent with the Web Chat channel enabled (set in the Agents module). Without one, the create flow shows an Agent Required prompt with a Go to Agents link.
• Your plan's web chat widget allowance. New workspaces include one widget; more require a higher plan. Reaching the limit opens an upgrade dialog instead of the create form.

Create and customize a widget

1. On the Web Chat page, click Create Widget (for the first one, use the Create Your First Widget card).
2. Fill in the modal titled Create Web Chat Widget. A Live Preview at the top reflects your changes as you type.
3. Click Create Widget to save.

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.
• Allowed Domains is enforced at runtime: when the list is set, the widget refuses to start chats from any other site. With no domains configured, the widget works on any website.
• 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 (Agent: {name}), 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 (Embed Code for {name}) offers three paths:

Each snippet already contains your widget's ID and always points at the production URL, so it works from any site. The basic snippet looks like this:

<script>
  (function() {
    window.HeliosChat = {
      widgetId: 'YOUR_WIDGET_ID',
      apiUrl: 'https://heliosvisionai.com'
    };
    var script = document.createElement('script');
    script.src = 'https://heliosvisionai.com/widget/helios-chat.js';
    script.async = true;
    document.body.appendChild(script);
  })();
</script>

The With Visitor Identification variant adds optional keys inside window.HeliosChat:

window.HeliosChat = {
  widgetId: 'YOUR_WIDGET_ID',
  apiUrl: 'https://heliosvisionai.com',

  // Optional: pre-identify your visitors
  // visitorName: 'User Name',
  // visitorEmail: 'user@example.com',
  // metadata: { customerId: '123', plan: 'premium' }
};

Installation steps: copy the snippet, paste it just before the </body> tag in your HTML, save and deploy, and 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 (some plans are unlimited). 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 Show branding toggle stays on.

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.
• Keep the snippet on every page of your site, loaded exactly once, so the button is available everywhere.

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.
• The embed snippet always targets the production URL, so it works even while you develop locally.

Related

• Web Chat
• Conversations
• Agents
• Teams