Skip to main content
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)

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

1

Open the dialog

On the Web Widgets tab, click Create Widget.
2

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

Select the flow

In Flow, select the flow that answers the visitors.
4

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

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. The Name, Flow and Allowed sites fields are filled in (dark)

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. On a site that is not in the list, the launcher and the chat panel do not show. 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: 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, Visibility, 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.

Visibility

The Start hidden switch sets how the widget starts on each page.
The Status card shows Active: sites show the widget. The Visibility card shows the Start hidden switch, off, with its help text about DialAI("hide") and DialAI("show") (light)The Status card shows Active: sites show the widget. The Visibility card shows the Start hidden switch, off, with its help text about DialAI("hide") and DialAI("show") (dark)

The Status and Visibility cards in the side panel of a widget

  • Off (the default) — the launcher shows when the page loads.
  • On — the page shows no launcher until the code of your page calls DialAI("show").
In both cases, the code of your page can show and hide the widget at any time. See Show and hide the widget. A change to this switch shows on a page the next time that the page loads.

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)

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

When somebody saves a change, the tab shows a bar: 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. When Start hidden is on, the sample site starts with no launcher, as your site does. Use the Show the chat and Hide the chat buttons on the sample site. When the widget has a token issuer, you can also chat as a signed-in customer. See Act as a customer.

Put the widget on your site

1

Copy the embed code

On the Embed code card, click Copy.
2

Paste it into each page

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

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 with the script tag and the Copy button (dark)

The Embed code card

The embed code has this shape:
Always copy the embed code from the page of the widget, because it has the correct values for your deployment.

What visitors see

  • The launcher shows in the corner that you set in the appearance. When Start hidden is on, it shows only after your page calls DialAI("show").
  • On a screen of 480 px or less, the open chat panel covers the full page.
  • An answer of the agent can have bold and italic text, lists and links. A link opens in a new tab. Only https: and mailto: addresses become links.
  • 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 shows the new launcher after a maximum of 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 show and hide the widget, 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:
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

To tell the widget who a signed-in customer is, give init an identity function. To let a visitor start the sign-in of your site from the chat, give init a signIn function. See Signed-in visitors.

Show and hide the widget

Your page decides when the widget shows. This is useful, for example, to show the chat only on some pages, or only after a visitor accepts your cookie settings.
  • To start with no launcher, set Start hidden on the page of the widget. Then call DialAI("show") when the widget must show.
  • To hide a widget that does not start hidden, call DialAI("hide") before the script loads. The launcher then never shows until your page calls DialAI("show").
  • The last show or hide of your page wins over the Start hidden switch.
A hidden widget shows no launcher, no count of unread messages and no chat panel. It also does not load the chat. hide does not end the conversation: when your page shows the widget again and the visitor opens the panel, the conversation is still there.

Sign out

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, and when your page goes to another page immediately after the call. A logout acts in every tab of the browser that shows the widget:
  • The conversation goes from the chat panel at once, and the panel closes.
  • A new chat starts only when somebody opens the panel again.
  • The browser removes the copies of the conversation that it keeps for the widget.

Events

In the text of a sent message, the platform masks sensitive data, such as a card number. Your page never gets the text that the visitor typed. When the widget continues a conversation on a new page, your page does not get the messages, handoffs and page actions of that conversation again. This example opens the chat from a “Chat with us” link, and records each handoff:
Put this code after the queue function, so that DialAI exists when it runs.

Page actions

A function of the flow can tell your page to do something. For example, after the agent changes the customer’s data, your page can read its data again. Or the agent can send the visitor to a page of your site. The function sends a page action with helpers.getWebWidget().sendToPage(name, data):
  • name is a short identifier: a letter, then a maximum of 63 letters, digits, _, . or -.
  • data is a JSON object of a maximum of 4 KiB. If you leave it out, it is {}.
  • The answer is { outcome: "sent" }, or { outcome: "notSent", reason } when the conversation is not a web widget conversation, is a test run, or has ended.
Your page gets the action with the action event:
A page action comes from the conversation, which the visitor controls. It is never proof of identity. Check each value before your page uses it, as you check any input from a visitor. For example, go only to a path on your own site.
The agent, the review, the summary and the classification of the conversation do not see page actions.

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

Best practices

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.