> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conduit.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect widget

> Enable real-time communication with website visitors through an embeddable chat interface.

## Overview

The chat widget lets visitors on your website start a conversation from any page. Widget conversations can be configured to arrive in your Conduit inbox alongside every other channel, so your team and your agents can handle them the same way they handle SMS, email, or WhatsApp.

The widget is customizable end to end: the header, greeting, assistant name, colors, launcher icon, and the options a visitor sees when they open it.

## Where widget conversations land

Website visitors usually arrive as unrecognized contacts, since they reach you without a phone number or email that already belongs to a contact in your workspace.

Routing for the widget is handled entirely through **user options** (explained below). Each option is mapped to an inbox, so the conversation goes wherever the option the visitor selected points. A "Book a stay" option can go to your Guest inbox while "Report an issue" goes to Maintenance.

<Note>
  User options are the only way to route widget conversations. Inbox routing rules do not cover the widget, so if an option has no inbox assigned, the conversation lands in the **Unmapped** inbox.
</Note>

<Tip>
  If widget conversations keep collecting in Unmapped, check that every user option on the widget has an inbox assigned.
</Tip>

Once a conversation reaches an inbox, your V3 agent can pick it up like any other channel. See [Road to Autopilot](/build-your-agent/road-to-autopilot/overview) for moving from copilot to autopilot.

## Setup

Navigate to **Settings > Widget** under Channels and select the widget you want to configure. The settings page is split into six numbered sections, with a live preview on the right. Changes are not applied until you click **Update**.

### 1. Design

Control how the widget looks and what it says.

| Setting | What it does |
| - | - |
| **Header** | The heading shown at the top of your widget |
| **Name** | The name of your assistant |
| **Greeting** | The initial message shown when the widget opens |
| **Post Form Message** | Shown after the visitor submits the form |
| **Logo** | The image shown in the widget. Recommended size is 256×256 px |
| **Color** | The inbound message bubble color |
| **Widget Launcher** | The color and icon of the launch button |
| **Enable WhatsApp** | Gives visitors the option to message your WhatsApp instead |
| **Allow anonymous conversations** | Skips the contact form and lets visitors start chatting immediately |
| **Auto-insert form fill params on links** | Appends UTM and collected form values to links clicked in the widget |
| **Default Country** | The default country code for the phone number input |

<Note>
  Turning on **Allow anonymous conversations** means you will not collect a name or email before the chat starts. Visitors reach you faster, but the conversation arrives without contact details attached.
</Note>

### 2. User Options

User options are the choices a visitor sees when the widget opens, and they are how widget conversations get routed. Click **Add Option** and choose one of:

* **Route to Inbox**: send the visitor's conversation to a specific inbox when they click this option
* **Redirect to URL**: send the visitor to an external URL
* **Embed a form**: open a form directly within the website

Each option has an icon, the button text the visitor sees, and its destination. Tick **Custom post-form message** to override the default post-form message for that option alone.

Drag and drop to reorder options. They appear in the widget in the order shown, top to bottom.

<Tip>
  Give each inbox its own option so conversations sort themselves at the point the visitor chooses. A "Book a stay" option pointing at Guest and a "Report an issue" option pointing at Maintenance saves your team reassigning conversations later.
</Tip>

### 3. Add to your website

Choose **HTML** or **Google Tag Manager**, then copy the snippet. For the HTML snippet, paste it right before the closing `</head>` tag on every page where the widget should appear. Adding it to a shared template or layout covers your whole site at once.

The snippet carries a `data-widget-id` that is unique to this widget, so copy it from the widget you configured rather than reusing one from elsewhere.

Expand **Pre-fill contact info on authenticated pages** if visitors are already signed in on your site and you want their details carried into the widget.

### 4. Programmatic API

Control the widget from your own code. These methods are available on `window.ConduitSettings` after the widget loads.

| Method | What it does |
| - | - |
| `expand()` | Opens the chat window |
| `collapse()` | Closes the chat window |
| `hide()` | Hides the widget entirely |
| `show()` | Shows the widget after hiding |

Use these to open the chat from your own call-to-action button, close it when a modal opens, or hide the widget on pages where it does not belong, such as checkout.

### 5. Trusted Domains

List the domains and subdomains where this widget is allowed to load, separated by commas. Use `*.example.com` to cover all subdomains. Leaving the field blank allows any domain.

<Tip>
  Setting trusted domains is optional but worth doing. It stops your widget loading anywhere you did not intend.
</Tip>

### 6. Email Notifications

Turn on **Enable email notifications** to email visitors new replies after they leave the widget, so they can continue the conversation. Add a **Support page URL** to include a link in that email that brings them back.

## Previewing before you publish

The preview panel on the right shows the widget as visitors will see it. Switch between the **Start**, **Form**, and **Chat** states to check each step, and toggle **Open** and **Closed** to see the launcher as well as the expanded widget.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Where do widget conversations go?">
    You configure the destination inbox under **User Options** in section 2: map each option to an inbox, and the conversation goes to whichever inbox matches the option the website visitor selected. If an option has no inbox assigned, the conversation lands in Unmapped. The conversation stays in the inbox after the chat ends, so you can follow up later.
  </Accordion>

  <Accordion title="Do I need to add the code to every page of my site?">
    The widget only appears on pages that include the snippet. Adding it to a shared template or layout is the simplest way to have it available across your whole site. Use `hide()` from the Programmatic API to suppress it on specific pages.
  </Accordion>

  <Accordion title="Can I change how the widget looks and what it says?">
    Yes, under **Settings > Widget** in Channels. Section 1 covers the header, greeting, assistant name, logo, colors, launcher icon, and the message shown after a visitor submits their details.
  </Accordion>

  <Accordion title="Can visitors chat without giving their contact details?">
    Yes. Turn on **Allow anonymous conversations** in section 1 to skip the contact form. The tradeoff is that the conversation arrives without a name or email attached.
  </Accordion>

  <Accordion title="What are Trusted Domains for?">
    They limit where your widget will load, so it only appears on domains you have listed. Leaving the field blank allows any domain.
  </Accordion>

  <Accordion title="Can I open the chat from my own button?">
    Yes. Call `window.ConduitSettings.expand()` from your button's click handler. See the Programmatic API section for the full set of methods.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.