> ## Documentation Index > Fetch the complete documentation index at: https://docs.dialai.ca/llms.txt > Use this file to discover all available pages before exploring further. # Web Widgets > Put a chat with one of your flows on your website, with a launcher in the corner of each page. The Web Widgets tab shows a list of widgets with their status, flow, visitors, allowed sites and update time (light) The Web Widgets tab shows a list of widgets with their status, flow, visitors, allowed sites and update time (dark) A **web widget** puts a chat with one of your flows on your own website. The widget adds a launcher in a bottom corner of each page. A visitor clicks the launcher, and a chat panel opens on the same page. Web Widgets are the new way to put chat on a website. They replace the legacy web chat (chat links on the **Web (Legacy)** tab, with the [iframe](/iframe-integration) or the [script tag](/script-tag-integration)). Use a web widget for each new site. A widget has these parts: * **A flow** — the flow that answers the visitors. * **Allowed sites** — the sites that can show the widget. No other site can show it. * **An appearance** — a preset and your changes to it. See [Widget appearance](/web-widget-appearance). * **Sign-in** — optional. A portal that signs its customers in can tell the widget who the customer is. See [Signed-in visitors](/web-widget-sign-in). ## Find Web Widgets Go to **Agent > Points of Contact** and select the **Web Widgets** tab. The tab shows only when your role has the `web-widgets:list` permission. Other actions need other permissions: | Permission | What it lets you do | | - | - | | `web-widgets:list` | See the **Web Widgets** tab and the list of widgets. | | `web-widgets:read` | Open the page of a widget. | | `web-widgets:create` | Create a widget with **Create Widget**. | | `web-widgets:update` | Change a widget: its status, allowed sites, appearance and sign-in. | | `web-widgets:simulate` | Use **Act as a customer** on the **Try it** card. | The list has these columns: **Status**, **Widget**, **Visitors**, **Allowed sites** and **Updated**. Active widgets are at the top. Use the **Status** filter to show only **Active** or **Off** widgets. Click a row to open the page of that widget. ## Create a widget On the **Web Widgets** tab, click **Create Widget**. In **Name**, type a name for the site or the page that shows the widget. An example is "Billing help on the account page". Each widget in your tenant must have a different name. In **Flow**, select the flow that answers the visitors. In **Allowed sites**, type the address of a site, such as `https://www.example.com`. Click **Add**. Do this again for each site that shows the widget. Click **Create Widget**. The page of the new widget opens. The Create Widget dialog. The Name, Flow and Allowed sites fields are filled in (light) The Create Widget dialog. The Name, Flow and Allowed sites fields are filled in (dark) A new widget is active. Each visitor is anonymous until you set up [sign-in](/web-widget-sign-in). The appearance is the **Classic** preset until you change it. ## Allowed sites The allowed sites are a security control. A site that is not in the list cannot show the widget. On that site, the launcher does not show, and the browser blocks the chat panel. If the list is empty, no site can show the widget. Each entry is an origin: a scheme, a host and an optional port. The widget ignores the path of an address. These forms are permitted: | Form | Example | Notes | | - | - | - | | One site | `https://www.example.com` | The usual form. | | All subdomains of a domain | `https://*.example.com` | Not permitted on a public suffix, such as `*.co.uk` or `*.github.io`. | | A site with a port | `https://portal.example.com:8443` | The platform removes a default port (`:443` on https). | | A local test site | `http://localhost:3000` | Only `localhost` and `127.0.0.1` can use `http`. | A widget has a maximum of 50 allowed sites. The list in the **Create Widget** dialog starts with the site of the Dial AI dashboard. This lets you try the widget on the **Try it** card at once. Keep this entry while you use **Try it**. To change the list later, click the edit (pencil) icon beside **Allowed sites** on the page of the widget. Add or remove sites, then click **Save**. ## The page of a widget The page has these cards: **Try it**, **Appearance**, **Embed code** and **Sign-in**. The side panel shows the **Status**, **Flow**, **Visitors**, **Allowed sites**, **Look**, **Limits** and **Created** date. ### Status The **Status** switch turns the widget on or off for all sites at the same time. * **Active: sites show the widget** — each allowed site shows the launcher. * **Off: no site shows it** — the launcher goes away, and the widget starts no new session. Use **Off** to stop a widget. The page has no delete action. ### Limits **Limits** shows the maximum number of conversations that the widget starts in one day (UTC), or **No daily limit**. You cannot change the limit on this page. ## Try it The **Try it** card shows a sample website with the widget on it. Click the launcher in its bottom corner and chat as a visitor does. A chat on the sample site is a real conversation with the flow of the widget. The page of a widget. The chat panel is open on the sample site, with a question and the answer of the flow (light) The page of a widget. The chat panel is open on the sample site, with a question and the answer of the flow (dark) * **Start again** loads the sample site again. * The **Open the sample site in a new tab** icon button opens the sample site in a new browser tab. In the tab, the widget has the full window, so it shows its desktop layout. The sample site in a full browser tab, with the chat panel open in the bottom right corner (light) The sample site in a full browser tab, with the chat panel open in the bottom right corner (dark) The new tab reads the widget again each 3 seconds. When somebody saves a change, a bar shows **The theme has changed.** or **The widget has changed.** Click **Reload** to show the change. The sample site cannot show the widget in these conditions. The card then shows the reason. | Message | What to do | | - | - | | This page (…) is not one of the widget's allowed sites, so the widget cannot show here. | Add the site of the dashboard to **Allowed sites**. | | The widget is off, so no site shows it. | Set **Status** to **Active**. | | The chat widget is not available on this deployment… | Contact your account representative. | When the widget has a sign-in provider, you can also chat as a signed-in customer. See [Act as a customer](/web-widget-sign-in#test-the-paths-with-act-as-a-customer). ## Put the widget on your site On the **Embed code** card, click **Copy**. Paste the code immediately before the `` tag of each page that shows the widget. Make sure that the site of each page is in **Allowed sites**. The Embed code card with the script tag and the Copy button (light) The Embed code card with the script tag and the Copy button (dark) The embed code has this shape: ```html theme={null} ``` Always copy the embed code from the page of the widget. The page writes the correct API host, tenant and widget ID for your deployment. Do not type the code yourself. The script adds the launcher to the page. The chat panel loads only when a visitor opens it. ### What visitors see * The launcher shows in the corner that you set in the appearance. * On a screen of 480 px or less, the open chat panel covers the full page. * The **Escape** key closes the panel. * If the chat cannot load in 15 seconds, the panel shows "The chat could not load." and a **Try again** button. A page that a visitor opens after a change shows the change. A page that stays open reads the launcher again each 30 minutes. ## Control the widget from your page The embed code also makes a JavaScript function, `DialAI`, on your page. Your page can use it to open the chat, to listen to events, and to give the widget a sign-in token. ### Call `DialAI` before the script loads To call `DialAI` before the script loads, add a small queue function first. Then call `init` yourself, and remove the `data-tenant`, `data-widget-id` and `data-host` attributes from the script tag: ```html theme={null} ``` Copy the values of `tenant`, `widgetId` and `host` from the embed code of the widget. Only the first `init` has an effect. The `data-tenant` attribute on the script tag is also an `init`, and it runs first. If you keep the attributes and also call `init`, the widget ignores your `init` and its options, such as `identity`. ### Commands | Command | What it does | | - | - | | `DialAI("init", { tenant, widgetId, host, identity })` | Adds the launcher. `host` and `identity` are optional. | | `DialAI("open")` | Opens the chat panel. | | `DialAI("close")` | Closes the chat panel. | | `DialAI("toggle")` | Opens the panel when it is closed, and closes it when it is open. | | `DialAI("logout")` | Ends the session of the visitor in the widget. | | `DialAI("on", event, handler)` | Calls `handler(payload)` for each event of that type. | | `DialAI("emit", "navigated", { url, title })` | Tells the widget that the page went to a different address. The widget accepts this event but does not use it yet. | Call `DialAI("logout")` when a person signs out of your site. Then the next person on the same browser does not see the conversation of the previous person. The logout works also when the chat panel did not open yet. To tell the widget who a signed-in customer is, give `init` an `identity` function. See [Signed-in visitors](/web-widget-sign-in#give-the-widget-a-token). ### Events | Event | Payload | When | | - | - | - | | `state` | `{ open }` | Each time the panel opens or closes. | | `conversation` | `{ event }`, with `event` one of `"started"`, `"ended"` or `"handoff-started"` | When a conversation starts, ends, or goes to a human agent. | | `message` | `{ direction, text, at }`, with `direction` one of `"received"` or `"sent"` | For each new message. | The `text` of a `sent` message is the text that the platform stored. The platform masks sensitive data, such as a card number, before it stores the text. Your page never gets the text that the visitor typed. This example opens the chat from a "Chat with us" link, and records each handoff: ```html theme={null} Chat with us ``` Put this code after the queue function, so that `DialAI` exists when it runs. ### Style the launcher Your page can change the launcher with CSS `::part()` rules. Your page cannot change the chat panel or the theme. See [Widget appearance](/web-widget-appearance#style-the-launcher-from-your-page). ## Web Widgets and the legacy web chat | | Web Widgets | Web (Legacy) | | - | - | - | | Where | **Points of Contact > Web Widgets** | **Points of Contact > Web (Legacy)** | | On your site | One script tag. It adds a launcher and a chat panel. | An iframe or the `dial-ai.js` script with `renderModal`. | | Which sites | Only the allowed sites. | Any site that has the chat link. | | Look | Presets and overrides, set on the dashboard. | The tenant theme, or `brandVariants` on the page. | | Customer identity | Tokens from your portal, checked by the platform. See [Signed-in visitors](/web-widget-sign-in). | Chat links with baked-in context. See [Passing context securely](/integration-context). | | Status | Current. | Deprecated. Chat links still work for now. | ## Best practices | Practice | Reason | | - | - | | Make one widget for each site or each part of a site. | Each widget has its own allowed sites, look and flow. The name shows in the list. | | Add only the sites that you own to **Allowed sites**. | Any allowed site can show your flow to its visitors. | | Test on the **Try it** card before you paste the embed code. | You see the same widget that your visitors see. | | Set **Status** to **Off** to stop a widget at once. | All sites stop it. You do not have to change each page. | ## Related Presets, colours, fonts and the launcher. Tell the widget who your customer is. All the channels that connect a flow to customers. Build the flow that answers your visitors. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.