Widget embed & API

Embed the widget

The simplest integration is the script tag from Widget Settings:

<script src="https://YOUR_WORKSPACE_DOMAIN/widget/chatbot.js" data-key="YOUR_WIDGET_KEY" defer></script>

Put it just before </body>. The widget renders in its own shadow root, so your site’s styles don’t affect it and it doesn’t affect your page. See Website chat widget for the settings.

Build your own chat interface

To design the chat yourself, call the same public endpoints the widget uses. They don’t need an API token — the widget key identifies your widget — and they enforce your widget’s Allowed Domains, based on the request’s Origin or Referer header.

• Base URL: https://YOUR_WORKSPACE_DOMAIN/api/widget
• Limit: 30 requests per minute per IP address

Get the widget’s settings

{
  "bot_name": "Assistant",
  "welcome_message": "Hi! How can I help you today?",
  "theme_color": "#2f7cf6",
  "enabled": true
}

Start or resume a session

{
  "session_id": "4a7c2e…",
  "lead_token": "9f1b6d…",
  "name": "Sara",
  "welcome_message": "Hi! How can I help you today?",
  "messages": []
}

When a conversation is resumed, messages holds the earlier messages — each with a role of visitor or bot — and welcome_message is null. Keep session_id and lead_token in the visitor’s browser and send them back next time. The visitor is recorded as a lead at this step.

Send a message

{
  "reply": "We deliver every day between 9 am and 9 pm.",
  "session_id": "4a7c2e…"
}

Errors

Errors return { "error": "…" } with one of these status codes: