Signing visitors in the widget

The chat widget on your site can be given values for the agent's variables. Values a page collects on its own are whatever the visitor typed into the address bar; values your server signs are ones the agent can act on.

How it works

1. Under Trusted visitor details on the agent's Connect → Website widget tab, choose Create a signing secret. Keep it on your server.
2. For each page load, your server signs the values it knows to be true — a name, a customer id, a plan — into a short-lived token.
3. The page hands the token to the widget: Aigently.identify(token), or a data-identity line on the widget's snippet.
4. The platform checks the signature before the values reach the agent. A value from a token is recorded as identity_token in the conversation's variable_sources.

Sign a token

The token is v1.<payload>.<signature>: the payload is JSON — {"exp": <unix time>, "v": {…}} — in base64url, and the signature an HMAC-SHA256 of v1.<payload> with the secret, also base64url. Here it is in your language:

#!/bin/sh
# Sign an identity token by hand with openssl, to try the chat widget before your server does it.
# The secret is in AIGENTLY_IDENTITY_SECRET; the token lives for five minutes.
set -eu
base64url() { base64 | tr -d '\n=' | tr '+/' '-_'; }

expires=$(($(date +%s) + 300))
body="$(printf '{"exp":%s,"v":{"first_name":"Sara","customer_id":"C-1042"}}' "$expires" | base64url)"
signature="$(printf 'v1.%s' "$body" \
  | openssl dgst -sha256 -hmac "$AIGENTLY_IDENTITY_SECRET" -binary | base64url)"
echo "v1.$body.$signature"

Rules

• Values are text, at most 20 of them. A value longer than 500 characters is cut.
• A token lives for at most an hour. Mint one per page load, five minutes is plenty. A token claiming to live longer is refused.
• A signature proves where the values came from, not who is at the keyboard. A page that signs the wrong person's name signs the wrong person's name. Treat these as personalisation, backed by your own login.
• phone is special: a signed phone tells the platform who the visitor is, so their chats join the history of calls from that number.