Skip to main content
The Chat Widget supports both text chat and live voice conversations in the browser. Visitors can type or speak to your assistant, switching between modes mid-conversation without losing context.

​
Overview

The widget functions as a 24/7 front desk on your website:
  • Greets visitors with suggested prompts
  • Answers from your knowledge base
  • Supports both typed (Chat) and spoken (Voice) conversations
  • Collects information through forms
  • Escalates to human agents when needed

​
Chat vs Voice

Visitors can switch between modes during a conversation. The assistant maintains full context when switching from chat to voice or vice versa.

​
Widget Templates

Four starter templates optimize the widget for different use cases:

​
Enabling Voice

Voice conversations require three conditions:
  1. The assigned assistant must have a published voice agent
  2. The widget must have voiceEnabled set to true
  3. The hosting page must use HTTPS (browsers block microphone access on HTTP)
When these conditions are met, the Chat | Voice toggle appears automatically.

​
Publishing a Voice Agent

1

Create or open an assistant

Navigate to Assistants and create a new assistant or open an existing one.
2

Configure voice settings

Open the Voice Lab tab. The assistant ships with a default voice. Click the voice name to change it, and use Start Call to test it.
3

Publish the assistant

Click Publish. This provisions the voice agent on the backend and makes voice available to any widget using this assistant.
The Voice toggle only appears when the assigned assistant has a published voice agent. Unpublished assistants show chat only.

​
Knowledge Base Integration

The knowledge base serves as the assistant’s handbook. Both chat and voice answer from the same knowledge base with identical accuracy.

​
Context-Aware Lookups

The assistant rewrites follow-up questions to include full context before searching:
  • Visitor: “What are your hours?”
  • Visitor: “What about the Batavia location?”
  • Internal rewrite: “What are the hours for the Batavia location?”
This ensures follow-up questions retrieve relevant answers instead of hallucinated responses. The system searches the knowledge base multiple ways and merges the best results, improving answer relevance and reducing misses.

​
Fallback Behavior

When a question falls outside the knowledge base scope, the assistant returns your configured fallback message instead of inventing an answer.
Knowledge base lookups are billed at $0.01 per lookup. The widget only performs lookups when needed (simple greetings like “hi” trigger no lookup).

​
Widget Tabs

The widget includes five optional tabs controlled by the visibleTabs setting: When only one tab is visible, the bottom navigation auto-hides for a clean chat interface.

​
Teaser Greeting

An optional Intercom-style greeting card appears above the launcher bubble with clickable suggestion chips. Configure the color with teaserColor (text auto-adjusts for contrast).

​
Roadmap Statuses

Roadmap items display one of four states:

​
Action Cards and Forms

The Home tab displays action cards that operate in three modes:

​
Form Field Types

Each field supports:
  • required validation
  • placeholder text
  • maps_to for CRM field mapping
NPS fields default to 0-10 range. Scale fields default to 1-5 but accept custom min and max values.

​
In-Chat Action Cards

When the assistant executes a tool, results render as interactive cards: Commerce Cards
  • Browse products (swipeable carousel)
  • Order management (list, status, cancel, return)
  • Checkout (start, apply discount, upsell)
  • Billing (subscription status, invoices)
Support Cards
  • Ticket management (create, check status, list)
  • Feedback submission
  • Booking (available slots, schedule)
  • Email verification
  • Human handoff
Cards only appear when the assigned assistant has the corresponding tool enabled and your store or helpdesk is connected.

​
Human Handoff

The widget supports three handoff modes via the handoffMode setting:

​
Escalation Cascade

Handoff requests fan out simultaneously across:
  • Dashboard inbox
  • Email
  • Slack
  • Configured webhooks
This escalation path operates even when the account is out of credit, ensuring leads never silently fail.

​
Live Agent Indicator

When a human joins the thread, the header displays “Live agent connected” so visitors know they are speaking with a person.

​
Office Hours

Configure office hours to display an honest “we’re away” state outside business hours instead of implying immediate availability.

​
Bug Reports

Enable bugReportEnabled to add a one-click screenshot capture tool for visitors to report issues.

​
Pre-Chat Form

Enable requirePreChatForm to collect visitor information before starting the conversation. Choose any combination of:
  • Name
  • Email
  • Phone
Visitors complete a short form (with custom heading and subheading) before the chat opens. Disabled by default.

​
Configuration Reference

​
Appearance Settings

​
Messaging Settings

​
Behavior Settings

voiceEnabled is server-authoritative. Voice only appears when the assigned assistant has a published voice agent, regardless of embed settings.

​
Installation

1

Create and configure widget

Navigate to Widgets, create a new Chat Widget V2, and assign a voice-enabled assistant.
2

Copy embed code

Open the Install section and copy the provided script snippet.
3

Add to your site

Paste the snippet before the closing </body> tag on your website.
The Chat | Voice toggle appears automatically when the assigned assistant has a published voice agent.
The hosting page must use HTTPS. Browsers block microphone access on HTTP pages.

​
Editor Sections

The Chat Widget V2 editor includes six configuration sections: A readiness checklist at the top flags incomplete configuration (e.g., “Voice enabled but no voice agent published”, “Human handoff enabled but no Slack connected”).