Signed-in visitors

Inside your customer portal, a chatbot can answer questions about the signed-in customer's own account, such as "which plan am I on?". Your server tells the chatbot who is asking and shares a short, plain-language summary of their account.

That summary is all the chatbot knows about the account. It never gets access to your systems. It only discusses that one account, with that one customer.

How it works#

1. A customer signs in to your portal.
2. Your server makes a short-lived token for them. The token says who they are and what the chatbot may know about their account. It's signed, so nobody can change it or make one up.
3. Your page hands the token to the chat.
4. The chat sends the token with every question. We check the signature and the expiry before using it.

How to set it up, in the Signed-in customers row on the Install tab, opens a short version of this guide in a pop-up.

You can get tokens in two ways:

What goes in a token#

Write context the way you'd brief a new support person. Keep it short and factual. For example:

Plan: Pro (paid, active)
Payments: Stripe connected
Bookings in the last 30 days: 42
Next invoice: 1 November, $49

Only include what you're happy for the customer to read back. Don't include passwords, card numbers or other secrets.

The details are fixed when the token is made. If the account changes, the chatbot only sees it in the next token.

Option 1: Ask us for each token#

Your server asks for a token with an API key from Settings › Ticket system. On the Connection tab, choose Your own system, then use the API keys row. Either kind of key works: Ticket system, or Ticket system with its own approval screen. The key must belong to the same platform as the chatbot.

Use the same address as in your chatbot's embed code.

POST https://<your Cerberius Agents address>/v1/chatbots/visitor-tokens
Authorization: Bearer sk_…
Content-Type: application/json

{
  "bot": "cb_…",
  "sub": "acct_1042",
  "name": "Fun Zone",
  "email": "[email protected]",
  "context": "Plan: Pro (paid)\nPayments: Stripe connected",
  "ttl_seconds": 3600
}

bot is the chatbot's data-bot value from the embed code. ttl_seconds is how long the token lasts: from 60 seconds to 24 hours, and one hour if you leave it out.

The answer:

{ "token": "v1.….…", "expires_at": 1760000000 }

Option 2: Sign tokens yourself#

1. 1

   Open the chatbot's Install tab. In the Signed-in customers row, click Create signing secret.

2. 2

   Click Copy to copy the secret, then Done. It starts with cbid_ and is shown only once.

3. 3

   Store it on your server, the same way you store other passwords and keys.

4. 4

   Make a token for each signed-in customer, as shown below.

A token is three parts joined by dots:

"v1." + base64url(JSON payload) + "." + base64url(HMAC-SHA256(secret, the part before))

• base64url is base64 with - and _ instead of + and /, and no = padding.
• The signature covers v1. plus the encoded payload, exactly as you send it.

Python#

import base64
import hashlib
import hmac
import json
import time


def b64url(data: bytes) -> str:
    return base64.urlsafe_b64encode(data).rstrip(b"=").decode()


def chat_token(secret: str, account_id: str, name: str, email: str, context: str,
               lifetime_seconds: int = 3600) -> str:
    payload = {
        "sub": account_id,
        "name": name,
        "email": email,
        "context": context,
        "exp": int(time.time()) + lifetime_seconds,
    }
    body = "v1." + b64url(json.dumps(payload, separators=(",", ":")).encode())
    signature = hmac.new(secret.encode(), body.encode(), hashlib.sha256).digest()
    return f"{body}.{b64url(signature)}"

Node.js#

import crypto from "node:crypto";

export function chatToken(secret, { sub, name, email, context }, lifetimeSeconds = 3600) {
  const payload = {
    sub,
    name,
    email,
    context,
    exp: Math.floor(Date.now() / 1000) + lifetimeSeconds,
  };
  const body = "v1." + Buffer.from(JSON.stringify(payload)).toString("base64url");
  const signature = crypto.createHmac("sha256", secret).update(body).digest("base64url");
  return `${body}.${signature}`;
}

Give the token to the chat#

On the portal page, set window.cerberiusChatSettings before the chat's script tag. getUserToken returns a token from your server, for example from an endpoint of your own:

<script>
  window.cerberiusChatSettings = {
    getUserToken: async () => (await fetch("/api/chat-token")).text(),
  };
</script>
<script src="https://…/widget.js" data-bot="cb_…" async></script>

The chat calls getUserToken:

• when it starts;
• again shortly before the token expires;
• once more if a question is refused because the token is no longer valid.

Conversations are kept separately for each account in the visitor's browser, so two people sharing a computer don't see each other's chats.

When the customer signs out, remove the chat:

window.CerberiusChat.destroy();

Only signed-in customers#

To keep a portal chatbot for signed-in customers only, switch on Only signed-in customers may use this chat on the Install tab. It's saved straight away. You need a signing secret first: until there is one, the switch is greyed out and says Create a signing secret first. If you use Option 1, ask us for one token and a secret is created for you.

With this on:

• On a page that gives no token, the chat doesn't appear at all.
• A question without a valid token is refused with "Please sign in to use this chat."

Without it, the same chatbot answers everyone, and only knows about an account when a token is given.

Test before going live#

On the chatbot's Instructions tab, switch on Test as a signed-in customer above the Try it chat. Enter a made-up Customer name and account summary in What your system would tell the chatbot about this account, then ask about "my account". This shows how the chatbot uses the summary, without any code.

Replacing the signing secret#

If the secret may have leaked, or someone who knew it leaves, click Replace signing secret and confirm with Replace. The new secret is shown once, like the first.

If you use Option 1, replacing the secret is safe: new tokens from our API use the new secret, and the chat asks your page for a fresh token when its old one is refused.

If it doesn't work#