

The Web Widgets tab on the Points of Contact page
- 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 theweb-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 with a name, a flow and one allowed site
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.
Visibility
The Start hidden switch sets how the widget starts on each page.

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").
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 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 new tab. The widget has the full window.
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
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:andmailto: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.
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:
tenant, widgetId and host from the embed code of the widget.
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 callsDialAI("show"). - The last
showorhideof your page wins over the Start hidden switch.
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
CallDialAI("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:
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 withhelpers.getWebWidget().sendToPage(name, data):
nameis a short identifier: a letter, then a maximum of 63 letters, digits,_,.or-.datais 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.
action event:
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
Related
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.