Signed-in Visitors

A web widget can sit behind the login of your portal. The server of your portal signs a token (a JWT) for the widget, for the customer who is signed in. The platform checks the token, and then it knows the customer. Values from the claims of the token become verified context parameters of the conversation. Your flow can trust these values, because the visitor cannot change them. Use this when a flow must act for one customer, for example to look up the balance of the customer’s account.

How it works

A customer signs in to your portal.
The widget asks your page for a token. Your page gets a new token for the customer from the server of your portal.
The platform checks the signature, the type, the issuer, the audience and the age of the token.
The platform reads the user id and the context parameters from the claims of the token, with the paths that you set.
The conversation starts. Functions in the flow read the context parameters as internal parameters.

The same user of one token issuer is the same visitor each time.

Who can chat

On the page of the widget, click Edit on the Sign-in card. In Who can chat, select a mode:

Mode	Label in the list	What the widget does
Anyone can chat. The widget accepts no sign-in.	Anonymous	It does not ask your page for a token. Each visitor is anonymous. This is the default.
Anyone can chat. A signed-in visitor is known to the agent by the claims of the portal’s token.	Sign-in optional	Without a signed-in customer, it starts an anonymous session. When the customer signs in, the conversation goes on as the signed-in customer. See A sign-in keeps the conversation.
Only signed-in visitors can chat.	Sign-in required	It starts only verified sessions. Without a signed-in customer, it shows “Sign in to chat.” and starts nothing.

The two sign-in modes need at least one token issuer. With Sign-in optional, an anonymous visitor can start a chat and then sign in to your portal in the same browser. The conversation then goes on as the signed-in customer:

The widget ends the anonymous session and starts a verified one. The conversation moves to the signed-in customer.
The context parameters from the token are available to the functions that run after the sign-in.
The agent is told that the visitor signed in.

When the customer changes or signs out

When another customer signs in on the page, the widget clears the conversation at once. It then starts again as the new customer. When the customer signs out, your page calls DialAI("logout"). The widget clears the conversation and closes the chat panel in each tab of the browser. A new chat starts only when somebody opens the panel again: as an anonymous visitor (Sign-in optional), or with “Sign in to chat.” (Sign-in required). See Sign out.

Add a token issuer

A token issuer is a signer of tokens that the widget trusts, usually the server of your portal. A widget can have a maximum of 20 token issuers. The iss claim of a token selects the token issuer.

Open the sign-in settings

On the page of the widget, click Edit on the Sign-in card.

Add a token issuer

Click Add a token issuer.

Fill in the fields

Fill in the fields in the table below.

Add the context parameters

Click Add a parameter for each value that the flow needs. See Map claims to context parameters.

Save

Select the mode in Who can chat, then click Save.

The Sign-in card. It shows the audience and the token type to copy. Sign-in is optional, and one token issuer has an issuer, a JWKS URL, a user id path, an oldest token of 120 seconds and one context parameter (light) — The Sign-in card with one token issuer

Field	What to type
Issuer (iss)	The exact `iss` value of the tokens that the server of your portal signs for this widget, such as `https://portal.example.com`.
How the portal signs its tokens	JWKS URL, Public key (JWK) or Shared secret (HS256). See Keys.
User id path	An RFC 9535 JSONPath query to the user’s id in the claims. The default is `$.sub`. See Map claims with JSONPath queries.
Oldest token, in seconds	1 to 300 (5 minutes). The platform refuses a token whose `iat` is older than this. The default is 120.
Context parameters	The parameters that the widget fills from the claims.

Keys

Select how your portal signs its tokens:

Kind	What to give	Algorithms
JWKS URL	The `https` URL of the JSON Web Key Set of your portal, such as `https://login.example.com/.well-known/jwks.json`. It must be on a public host.	ES256, ES384, RS256, PS256
Public key (JWK)	One EC (P-256 or P-384) or RSA public key, as JSON. Paste the public key only. The platform refuses a key that has a private part.	ES256, ES384, RS256, PS256
Shared secret (HS256)	A secret of 32 to 512 bytes that your backend also knows.	HS256

Use a JWKS URL when the server of your portal publishes one. Then a key rotation needs no change here. Use a Shared secret when your own backend signs a token for the widget. After you save, the secret does not show again. To keep the secret, leave the field empty when you edit the token issuer. To replace it, type a new secret. If the page shows “This deployment cannot store a shared secret. Use a JWKS URL or a public key.”, use one of the other kinds.

Keep a shared secret on your server. Never put it in the code of your page.

What the token must have

The platform sets the audience of each widget. You cannot change it. The Sign-in card shows the two values that each token must have, with a copy button for each:

Audience (aud) — urn:dial-ai:web-widget:<widget id>, with the id of this widget.
Type (typ header) — dial-ai-web-widget+jwt.

Give these values to the people who build your portal. Each token must have:

The header typ equal to dial-ai-web-widget+jwt.
The header alg: HS256 for a shared secret, or ES256, ES384, RS256 or PS256 for a key of your portal.
iss, equal to Issuer (iss).
aud, equal to the audience of the widget, or an array that holds it.
exp and iat. The iat must not be older than Oldest token, in seconds.
The claim that User id path finds. It must be text that is not empty, or a number.

The platform permits 60 seconds of clock difference. The type and the audience keep a token for another purpose from working on the widget. A token for one widget also does not work on another widget, also when the two widgets trust the same issuer.

Do not give the widget a token from your identity provider, such as an ID token or an access token for your own API. Such a token is for another audience. The server of your portal must sign a new token for the widget each time the widget asks for one.

Map claims with JSONPath queries

The User id path and each context parameter use a JSONPath query, as RFC 9535 defines it. The platform runs each path on the claims of the token. A path finds no value, one value, or more values. Example claims of a token. The aud, iat and exp claims are not shown.

{
  "sub": "user-123",
  "iss": "https://portal.example.com",
  "https://portal.example.com/claims": { "account": "A-1" },
  "x-tenant": "east",
  "profile": { "email": "a@example.com", "name": { "given": "Ada" } },
  "accounts": [
    { "number": "1001", "primary": true },
    { "number": "1002", "primary": false }
  ],
  "roles": ["a", "b", "c"]
}

Path	Result on these claims
`$.sub`	Finds `"user-123"`.
`$.profile.name.given`	Finds `"Ada"`. Each `.name` goes into a member of an object.
`$['https://portal.example.com/claims'].account`	Finds `"A-1"`. Put a member name in brackets and quotes when it has a character that is not a letter, a digit or `_`, such as `/`, `-` or `.`.
`$["x-tenant"]`	Finds `"east"`. You can use single quotes or double quotes.
`$.accounts[0].number`	Finds `"1001"`. The index of the first element is `0`.
`$.accounts[-1].number`	Finds `"1002"`. A negative index counts from the end, so `-1` is the last element.
`$.accounts[?@.primary == true].number`	Finds `"1001"`, the number of the primary account. A filter `[?…]` keeps each element for which its test is true. In the test, `@` is the element.
`$.roles`	Finds `["a", "b", "c"]`. An array is one value.
`$.missing`	Finds no value.
`$.accounts[*].number`	Finds two values, `"1001"` and `"1002"`. `[]` selects each element of the array. This is ambiguous*, so the platform does not use it.

Rules for a path

A path starts with $, the root of the claims. Do not put a space before $ or after the end of the path.
Use .name for a member whose name has only letters, digits and _, and does not start with a digit. For other names, use ['name'] or ["name"].
[*] selects each element of an array, and .* selects each member of an object. Thus they find one value for each element or member. To select one element, use an index or a filter.
A filter can use the functions of RFC 9535. For example, $.accounts[?search(@.number, '2$')].number finds "1002".
A path has a maximum of 1000 characters.

For all of the syntax, see RFC 9535.

Outcomes

Each path has one of three outcomes:

Outcome	Means	User id path	Context parameter
found	The path finds exactly one value.	If the value is text that is not empty, or a number, it is the visitor’s user id. Else the sign-in fails.	The platform sets the parameter.
absent	The path finds no value.	The sign-in fails.	The platform leaves the parameter out. The conversation starts.
ambiguous	The path finds two or more values.	The sign-in fails.	The platform leaves the parameter out. The conversation starts.

An ambiguous outcome is a mistake in the path, and only you can correct it. Some details about the outcomes:

A path cannot fail on the claims. A comparison of two values of different types is false. For example, $.accounts[?@.number > 1000].number finds no value, because each number is text and 1000 is a number.
A filter without a comparison only tests that the member is there. For example, $.accounts[?@.primary].number finds two values, because both accounts have primary. To test the value, write $.accounts[?@.primary == true].number.
A path into a value of a different type finds no value. For example, $.sub.inner finds no value, because sub is text.
An array or an object is one value. For example, $.roles is found, and gives the array ["a", "b", "c"].
A JSON null is a value, so a path to null is found. A context parameter then gets null if its schema permits it.

The check when you save

When you click Save, the platform reads each path. If a path is not a correct RFC 9535 JSONPath query, the field shows “This is not an RFC 9535 JSONPath query, such as

.sub or

.accounts[0].number”, then the problem that the platform found and its position in the path. For example, the platform refuses these paths:

$., because the path ends with a dot.
$.accounts[?@.number = '1001'], because a comparison uses ==, not =.
$.accounts[?like(@.number, '1')], because RFC 9535 has no function like.

This check finds only syntax mistakes. It cannot find a path that finds no value, or two values, in the tokens of your portal. To find those mistakes, use Act as a customer.

Map claims to context parameters

A context parameter is a parameter of your tenant that the widget fills from the claims of the token.

In Context parameters, click Add a parameter.
Select the parameter. To make a new parameter, type its name and select Add ‘name’.
Type the JSONPath query to the value in the claims, such as $.accounts[0].number.

When a conversation starts, the platform checks each value against the JSON schema of its parameter. If a value does not fit the schema, the platform leaves the parameter out. The conversation starts without it. A token issuer can map a maximum of 50 parameters. The values of all context parameters must be 4 KiB of JSON or less. If they are more, the sign-in fails. Functions in the flow read these values as internal parameters (context parameters). Your page gives the widget a token through the identity option of init. identity is a function with no arguments. It returns a promise of a token for the customer who is signed in now, or null when nobody is signed in. To use identity, call init yourself, and remove the data-tenant, data-widget-id and data-host attributes from the script tag. See Call DialAI before the script loads.

<script>
  window.DialAI = window.DialAI || function () { (DialAI.q = DialAI.q || []).push(arguments) };
  DialAI("init", {
    tenant: "<tenant>",
    widgetId: "<widget id>",
    host: "https://<api host>",
    identity: async function () {
      // Your backend checks the portal session and returns a new token as text.
      const response = await fetch("/session/widget-token", { credentials: "same-origin" });
      if (!response.ok) return null;
      return (await response.text()) || null;
    },
  });
</script>
<script async src="https://<api host>/widget/loader.js"></script>

The widget calls the function before each session start, and again about each 8 minutes to refresh the session. It also calls the function when a page loads with an anonymous session, so that a customer who signed in is known at once. Obey these rules:

Return a new token on each call.
Return null when nobody is signed in.
Return in less than 10 seconds. The widget counts no answer as null.
Keep the token under 32 KiB.

An error, a rejected promise, or a value that is not text counts as null. When a customer signs out of your portal, also call DialAI("logout"). Then the next person on the same browser does not see the conversation.

Sign the token on your server

The server of your portal signs a new token each time the identity function asks for one:

Your server checks the portal session of the customer.
It signs a JWT with the header typ: dial-ai-web-widget+jwt. It signs with HS256 and the shared secret of the token issuer. Or it signs with its own private key, and you give the public key or a JWKS URL to the token issuer.
It sets aud to the audience of the widget, and puts the verified values in the claims, for example the account number.
It returns the token to the identity function of your page.

Give the token a short life, for example 2 minutes. The chat can show a Sign in button that starts the sign-in of your portal. Give init a signIn function, with no arguments, that starts your sign-in, for example with a redirect to your login page:

DialAI("init", {
  tenant: "<tenant>",
  widgetId: "<widget id>",
  host: "https://<api host>",
  identity: getWidgetToken,
  signIn: function () {
    window.location.assign("/login?return=" + encodeURIComponent(window.location.href));
  },
});

The chat then shows the Sign in button in these cases:

Under “Sign in to chat.”, on a widget with Sign-in required.
In the conversation, under “Sign in to continue.”, when a function of the flow asks for a sign-in and the visitor is not signed in.

The chat panel opens again when the visitor comes back from the sign-in. With Sign-in optional, the conversation then goes on as the signed-in customer. Without a signIn function, the chat shows no button. A function of the flow asks for a sign-in with helpers.getWebWidget().requestSignIn():

const asked = await helpers.getWebWidget().requestSignIn();
if (asked.outcome === "notSent") {
  // asked.reason: "notWebWidget", "testRun", "conversationEnded", "alreadySignedIn" or "signInNotAvailable".
}

The answer is notSent with alreadySignedIn when the visitor is signed in, and with signInNotAvailable when the widget takes no signed-in visitors.

Test the paths with Act as a customer

Act as a customer lets you chat on the Try it card as a signed-in customer, with claims that you type. You do not need a token from your portal. You need the web-widgets:simulate permission, and the widget must have at least one token issuer.

Start

On the Try it card, click Act as a customer.

Select the token issuer

In Token issuer, select the token issuer to test.

Type the claims

In Claims (JSON), type the claims of a customer’s token. The field starts with a test user at the User id path. The maximum is 16 KiB.

Chat

Click Start as this customer. Then open the launcher on the sample site and chat.

The card then shows what the paths of the token issuer found in your claims:

Visitor id — Found, or the reason the sign-in fails:
- “The path finds nothing in the claims. The sign-in fails.”
- “Not an id. Use text that is not empty, or a number. The sign-in fails.”
- For an ambiguous path, the number of values and the first values. For example, the user id path $.accounts[*].number on the example claims above gives The path finds 2 values: "1001", "1002". It must find one. The sign-in fails.
Each context parameter — one of these:
- Set.
- “The path finds nothing in the claims”.
- “Does not fit: …” with the schema problem.
- For an ambiguous path, the number of values and the first values, then “It must find one, so the parameter is left out.”

The card shows a maximum of five values. When a path finds 50 values or more, the card says “50 or more values”.

The Try it card in a simulated session. Visitor id shows Found, ServiceAddress shows Set, and the chat panel shows an answer of the flow (light) — Act as a customer. The paths found the visitor id and set the context parameter.

The Try it card in a simulated session. Visitor id shows Found, ServiceAddress shows Set, and the chat panel shows an answer of the flow (dark) — Act as a customer. The paths found the visitor id and set the context parameter.

If a path finds two or more values, the card shows a warning: “A path of this token issuer has a mistake. Correct it in the sign-in settings: a real visitor gets the same result, and the widget logs the mistake as an error.” Click Stop to chat as an anonymous visitor again. The session of Act as a customer is a simulated session. It never shows the real conversations of that customer. When the platform refuses a token, the widget gets one of these codes. Your developers can see the code in the network tab of the browser.

Code	Means
`invalid_token`	Not a JWT, a bad signature, an algorithm that the key does not permit, no `exp` or `iat`, or an `iat` or `nbf` in the future.
`unknown_issuer`	No token issuer of the widget has the `iss` of the token.
`expired`	The `exp` of the token is more than 60 seconds ago.
`too_old`	The `iat` of the token is older than Oldest token, in seconds.
`bad_audience`	The `aud` of the token does not hold the audience of the widget.
`bad_type`	The header of the token has no `typ`, or a `typ` that is not `dial-ai-web-widget+jwt`. The token was not signed for the widget.
`no_user_id`	The User id path found no value, two or more values, or a value that is not text or a number. Empty text is not a user id.
`context_too_large`	The context parameters are more than 4 KiB of JSON.
`identity_required`	A refresh had no token, but the session needs a signed-in customer. The session ends.
`user_changed`	A refresh had a token of a different user. The session ends.

Best practices

Practice	Reason
Put only the values that the flow needs in the claims.	The values must be 4 KiB of JSON or less.
Use a filter to select one value from a list.	A path that finds two values is ambiguous, and the platform does not use it.
Test each token issuer with Act as a customer before you go live.	The save check finds only syntax mistakes.
Sign a new, short-lived token for each call of `identity`.	A stolen token is then useful for a short time only.
Call `DialAI("logout")` when a customer signs out.	The next person on the same browser then does not see the conversation.

Web Widgets

Create a widget and put it on your site.

Widget appearance

Presets, colours, fonts and the launcher.

Functions and events

Read context parameters in a function.

Building blocks

Make the parameters that the widget fills.

Get Started

Monitoring

Building & Managing Flows

Docs

Agent

Outbound

Integrations

Settings

Training hub

How it works

Who can chat

When the customer changes or signs out

Add a token issuer

Keys

What the token must have

Map claims with JSONPath queries

Rules for a path

Outcomes

The check when you save

Map claims to context parameters

Give the widget a token

Sign the token on your server

Test the paths with Act as a customer

Best practices

Web Widgets

Widget appearance

Functions and events

Building blocks

How it works

Who can chat

A sign-in keeps the conversation

When the customer changes or signs out

Add a token issuer

Keys

What the token must have

Map claims with JSONPath queries

Rules for a path

Outcomes

The check when you save

Map claims to context parameters

Give the widget a token

Sign the token on your server

Let the visitor sign in from the chat

Test the paths with Act as a customer

When a sign-in fails

Best practices

Related

Web Widgets

Widget appearance

Functions and events

Building blocks