Embedded web chat

Mint a session token (backend)#

Call POST /web-chat/session with your API key. phoneNumber must be E.164 and assigned to one of your tenant's assistants — it selects which assistant the visitor chats with.

curl -X POST https://core-api.heysadie.ai/web-chat/session \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phoneNumber": "+15555550123", "visitorId": "usr_abc123" }'

{
  "sessionToken": "eyJhbGciOi...",
  "expiresIn": 1800
}

visitorId is optional: a stable, unique-per-end-user identifier you control (your user id, or a random id persisted in the visitor's cookie/localStorage; 1–128 characters, letters, digits, and . _ : -). Supplying it keeps the conversation continuous across token refreshes and page reloads. Omit it for an ephemeral one-shot session.

Return sessionToken to your browser. The token has a 30-minute TTL (expiresIn seconds); after it expires the browser must request a fresh token from your backend.

Send messages (browser)#

The browser authenticates with the session token as a Bearer token — no API key involved. The visitor identity is sealed inside the token and cannot be spoofed from the browser.

const res = await fetch("https://core-api.heysadie.ai/web-chat/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${sessionToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text: "Do you have a table for two tonight?" }),
});
const { reply } = await res.json();

text is optional (max 4,000 characters) — omit it or send an empty string to trigger the assistant's opening greeting, which is a good way to start the widget.

{
  "reply": "Hi! I'd be happy to help with your reservation. What's your name?"
}

End the conversation (browser)#

When the visitor closes the chat, end the conversation explicitly:

await fetch("https://core-api.heysadie.ai/web-chat/end", {
  method: "POST",
  headers: { Authorization: `Bearer ${sessionToken}` },
});
// -> { "ended": true }