Web Widgets

The Web Widgets tab shows a list of widgets with their status, flow, visitors, allowed sites and update time (light) — The Web Widgets tab on the Points of Contact page

The Web Widgets tab shows a list of widgets with their status, flow, visitors, allowed sites and update time (dark) — The Web Widgets tab on the Points of Contact page

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 or the script tag). 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.
Sign-in — optional. A portal that signs its customers in can tell the widget who the customer is. See Signed-in visitors.

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.

Open the dialog

On the Web Widgets tab, click Create Widget.

Type a name

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.

Select the flow

In Flow, select the flow that answers the visitors.

Add the allowed sites

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.

Create 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 with a name, a flow and one allowed site

A new widget is active. Each visitor is anonymous until you set up 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 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 Try it card shows a chat on the sample site.

The page of a widget. The chat panel is open on the sample site, with a question and the answer of the flow (dark) — The page of a widget. The Try it card shows a chat on the sample site.

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 new tab. The widget has the full window.

The sample site in a full browser tab, with the chat panel open in the bottom right corner (dark) — The sample site in a new tab. The widget has the full window.

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.

Copy the embed code

On the Embed code card, click Copy.

Paste it into each page

Paste the code immediately before the </body> tag of each page that shows the widget.

Check the allowed sites

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

The Embed code card with the script tag and the Copy button (dark) — The Embed code card

The embed code has this shape:

<script async src="https://<api host>/widget/loader.js"
  data-tenant="<tenant>"
  data-widget-id="<widget id>"
  data-host="https://<api host>"></script>

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. 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:

<script>
  window.DialAI = window.DialAI || function () { (DialAI.q = DialAI.q || []).push(arguments) };
  DialAI("init", { tenant: "<tenant>", widgetId: "<widget id>", host: "https://<api host>" });
</script>
<script async src="https://<api host>/widget/loader.js"></script>

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.

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:

<a href="#" id="chat-link">Chat with us</a>
<script>
  document.getElementById("chat-link").addEventListener("click", function (event) {
    event.preventDefault();
    DialAI("open");
  });
  DialAI("on", "conversation", function (payload) {
    if (payload.event === "handoff-started") {
      console.log("The conversation went to a human agent.");
    }
  });
</script>

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 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.	Chat links with baked-in context. See Passing context securely.
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.

Widget appearance

Presets, colours, fonts and the launcher.

Signed-in visitors

Tell the widget who your customer is.

Points of Contact

All the channels that connect a flow to customers.

Flows

Build the flow that answers your visitors.

Get Started

Monitoring

Building & Managing Flows

Docs

Agent

Outbound

Integrations

Settings

Find Web Widgets

Create a widget

Allowed sites

The page of a widget

Status

Limits

Try it

Put the widget on your site

What visitors see

Control the widget from your page

Call `DialAI` before the script loads

Commands

Events

Style the launcher

Web Widgets and the legacy web chat

Best practices

Widget appearance

Signed-in visitors

Points of Contact

Flows

​Find Web Widgets

​Create a widget

​Allowed sites

​The page of a widget

​Status

​Limits

​Try it

​Put the widget on your site

​What visitors see

​Control the widget from your page

​Call DialAI before the script loads

​Commands

​Events

​Style the launcher

​Web Widgets and the legacy web chat

​Best practices

​Related

Widget appearance

Signed-in visitors

Points of Contact

Flows

Find Web Widgets

Create a widget

Allowed sites

The page of a widget

Status

Limits

Try it

Put the widget on your site

What visitors see

Control the widget from your page

Call `DialAI` before the script loads

Commands

Events

Style the launcher

Web Widgets and the legacy web chat

Best practices

Related