<!-- Source: https://docs.vinsi.ai/ai-phone-agents/website-widget -->
# Website Widget

Put your AI agent on any website as a floating button. Visitors can talk to it in the browser, chat by text, or ask it to call their phone.

Created: September 16, 2026

Updated: September 16, 2026

## Overview

The widget is configured per agent in the agent editor, under **🌐 Website Widget** in the Settings panel. You choose the channels, list the websites allowed to show it, then copy a short code snippet into your site. The button opens a panel with your agent's name and a _Powered by VINSI.AI_ footer.

New to the agent editor? Start with [Create your first AI Phone Agent](https://docs.vinsi.ai/getting-started/first-phone-agent).

## Before You Start

- **Save the agent.** Until it's saved, the section shows "Save your agent first to generate the widget embed code."
- Give it a **Welcome Message** and **Instructions**, and test it with **Talk**.
- Widget voice calls and Call me callbacks use your organization's minutes like any other call.
- For **Call me**, assign a phone number to the agent under **☎️ Telephony** (see [Outbound Calls](https://docs.vinsi.ai/telephony/outboundCalls)).

## Choose Channels

Under **Channels**, turn on any combination. New agents start with Voice only.

| Channel       | What the visitor does                                                                           | Uses                                                      |
| ------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| **Voice**     | Clicks the microphone and talks with the agent in the browser (microphone permission required). | The agent's voice, welcome message, and instructions      |
| **Text chat** | Types messages and reads the agent's replies.                                                   | **Chat instructions**, or the voice instructions if empty |
| **Call me**   | Enters a phone number and gets a call from the agent right away.                                | The agent's **Outbound Agent** tab                        |

With more than one channel on, the panel shows **Voice**, **Text**, and **Call me** buttons so visitors can switch. It opens on Voice first, then Text, then Call me.

### Chat Instructions

Appears when **Text chat** is on. These instructions are used only in text chat, so you can drop voice-only guidance (like spelling things out loud) and ask for short, well-formatted replies. Leave it empty to reuse the agent's main instructions. Click the expand button for the full-screen **Edit Chat Instructions** editor.

### Starter Messages

Appears only when **Text chat** is the _only_ channel. Starter messages are tappable suggestions shown under the greeting, e.g. _Book a service_, _Get a quote_, _Ask a question_.

- One per line, up to **4**; each is cut to 40 characters.
- Leave empty and suggestions are generated from the agent's instructions.
- In chat-only mode the panel opens with the agent's **Welcome Message** as the first chat bubble.

## Allowed Domains

List every website where the widget may appear — one per line or separated by commas. The helper text shows how many entries you have.

If **Allowed domains** is empty, the widget won't load anywhere. This protects your agent (and your minutes) from being embedded on other people's sites.

| Entry            | Allows                                                                   |
| ---------------- | ------------------------------------------------------------------------ |
| acme.com         | https://acme.com and any subdomain such as www.acme.com or shop.acme.com |
| support.acme.com | That subdomain and its own subdomains only                               |
| localhost:3000   | Local testing on that exact port                                         |

- Enter the host only. `https://` and any path are ignored.
- Plain domain entries require your site to use HTTPS.
- Click **Save** on the agent after changing domains. Changes apply on the next page load of your website.

## Get the Embed Code

1. Click **Get Widget Embed Code** to open **Embed Widget on Your Website**.
2. Under **Customize Your Widget**, set the options below. The **Preview** shows the button.
3. Click **Copy Code** ("Embed code copied to clipboard!").

| Option           | Choices                                                                    | Default     |
| ---------------- | -------------------------------------------------------------------------- | ----------- |
| **Button Text**  | Any short label                                                            | Let's Talk  |
| **Button Color** | Color picker or hex code                                                   | #000000     |
| **Button Shape** | Pill (Fully Rounded), Rounded Corners, Square, Circle (icon only, no text) | Pill        |
| **Shadow**       | Add shadow to button                                                       | On          |
| **Button icon**  | Chat bubble or Phone                                                       | Chat bubble |

The copied code looks like this (your agent ID is filled in):

Embed code

```
<!-- VINSI AI Agent Widget -->
<vinsi-agent
  agent-id="YOUR_AGENT_ID"
  button-text="Let's Talk"
  button-color="#000000"
  button-shape="pill"
  has-shadow="true"
  button-icon="chat"
  base-url="https://dashboard.vinsi.ai">
</vinsi-agent>
<script src="https://dashboard.vinsi.ai/widget/vinsi-widget.js" async type="text/javascript"></script>
```

Channels, instructions, starter messages, and allowed domains are read live from the agent, so you don't need to re-copy the code after changing them. Re-copy only if you change the button's look.

## Install on Your Website

1. Add your site's domain to **Allowed domains** and save the agent.
2. Paste the code before the closing `</body>` tag of your website — in your site template or footer so it appears on every page.
3. Publish your site, open it in a new tab, and click the button to test each channel.

| Platform            | Where to paste                                                                             |
| ------------------- | ------------------------------------------------------------------------------------------ |
| WordPress           | A footer-scripts plugin or your theme's footer (Custom HTML block works for a single page) |
| Wix / Squarespace   | Custom code / code injection, placed in the footer (body end), on all pages                |
| Webflow             | Project Settings → Custom Code → Footer Code                                               |
| Shopify             | Online Store → Themes → Edit code → theme.liquid, before </body>                           |
| Custom site / React | Your main HTML template before </body>                                                     |

## What Visitors See

- A floating button in the bottom-right corner of every page.
- **Voice** — "Click to talk", then "Connecting..." and "Call in progress". The red button hangs up.
- **Text** — "Type your message..." and **Send**. After 3 minutes without a message the chat ends ("Conversation ended").
- **Call me** — "Leave your number and we'll call you right away."
- Closing the panel with × ends the voice call or chat.

### How Call Me Works

1. The visitor enters a US/Canada phone number and clicks **Call me**.
2. VINSI immediately places an outbound call using the agent's **Outbound Agent** tab — its welcome message, instructions, voice, and voicemail message — from the agent's default outbound number (**Set as default** under ☎️ Telephony).
3. The visitor sees "Great! We're calling you now at …" and their phone rings.

Fill in the Outbound Agent tab before enabling Call me — write the welcome message as a callback ("Hi, this is Giselle from Acme returning your request from our website…"). Numbers on your Do Not Call list are not called.

## Conversations and Follow-up

Widget conversations appear in [Call Logs](https://docs.vinsi.ai/telephony/callLogs). Text chats are saved when they end, with a summary, a disposition chosen from the agent's **Dispositions**, and any **Call Data** fields found in the chat. They also trigger the agent's **After Call Webhook**, so [After Call Actions](https://docs.vinsi.ai/tools/after-call-actions) (emails and tickets) work for chats too.

## Troubleshooting

| Problem                                                                   | What to do                                                                                                            |
| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Button shows but the panel is blank or refuses to connect                 | Your site's domain isn't in **Allowed domains** (or the list is empty). Add it, save the agent, and reload your site. |
| Works on www. but not another host                                        | Add the parent domain (e.g. acme.com) so all subdomains are allowed.                                                  |
| Doesn't work on an http:// site                                           | Use HTTPS. Browsers also block the microphone on insecure pages.                                                      |
| No button at all                                                          | Check the snippet is in the published page (view source), the script tag is included, and agent-id is correct.        |
| "Unable to Connect" / "Origin not allowed"                                | Allowed domains problem — see the first row.                                                                          |
| "Agent not found or inactive"                                             | The agent was deleted or deactivated. Use an active agent's embed code.                                               |
| Voice: nothing happens after "Click to talk"                              | The visitor must allow microphone access in the browser.                                                              |
| Call me shows an error under the number (e.g. "Could not place the call") | Assign a phone number to the agent and set a default outbound number, then try again.                                 |
| Call me: button stays disabled                                            | Enter a complete 10-digit US/Canada number.                                                                           |
| Starter messages don't show                                               | They only show when Text chat is the only channel, before the visitor sends a message.                                |
| Chat answers sound like a phone script                                    | Write **Chat instructions** for text.                                                                                 |