Sign in

v51

latestOpenAPI 3.0.0raw.githubusercontent.com2026-08-014102371.0 MB
Webchat

Create a new webchat widget.

Creates a new webchat widget configuration. Also issues a direct hash for anonymous visitor authentication.

post/webchat_widgets

Request body

namestring required

Name of the widget.

session_flow_idstring uuid required

Fires once per Session, at session creation/start. Returned from the POST /flows or GET /flows response.

message_flow_idstring uuid

Optional. Fires on every inbound message, independently. Returned from the POST /flows or GET /flows response.

session_idle_timeoutinteger

Session idle timeout in seconds before the session is automatically ended. Defaults to 1800 (30 minutes) when omitted.

Example request

{
  "name": "Support Widget",
  "session_flow_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "message_flow_id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
  "session_idle_timeout": 1800,
  "theme_config": {
    "primary_color": "#1a73e8",
    "secondary_color": "#f5f5f5",
    "header_background_color": "#1a73e8",
    "header_text_color": "#ffffff",
    "logo_url": "https://cdn.example.com/logo.png",
    "position": "bottom_right",
    "theme_mode": "light",
    "header_title": "Support",
    "header_subtitle": "We usually reply in a few minutes",
    "connecting_indicator_enabled": true,
    "connecting_indicator_text": "Connecting…",
    "typing_indicator_enabled": true,
    "border_radius": "rounded",
    "font_size": "default"
  }
}

Response

Details of the created widget.

idstring uuid required

The unique identifier of the widget. Returned from the POST /widgets or GET /widgets response.

customer_idstring uuid required

The unique identifier of the associated customer. Returned from the GET /customers response.

namestring required

Name of the widget.

status'active' | 'inactive' required

The status of the widget.

session_flow_idstring uuid required

Fires once per Session, at session creation/start (POST /webchat_sessions) -- bin-conversation-manager owns Create+Execute for this Flow's activeflow. Returned from the POST /flows or GET /flows response.

message_flow_idstring uuid

Optional. When set, fires an independent, stateless activeflow on EVERY inbound message (mirrors bin-conversation-manager's Account.MessageFlowID/Number.MessageFlowID pattern for LINE/WhatsApp/SMS). Returned from the POST /flows or GET /flows response.

session_idle_timeoutinteger required

Session idle timeout in seconds before the session is automatically ended.

direct_hashstring

Hash used by the embed script (data-hash attribute) to authenticate anonymous visitors via POST /auth/boot. Returned on every response (GET, List, Create, Update, direct_hash_regenerate) -- this value is embedded directly in the customer's public website HTML by design, so it is not a traditional secret; hiding it from GET responses would only make it harder for the customer's own admins to retrieve it.

tm_createstring date-time

Timestamp when the widget was created.

tm_updatestring date-time

Timestamp when the widget was last updated.

tm_deletestring date-time

Timestamp when the widget was deleted.

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "customer_id": "7c4d2f3a-1b8e-4f5c-9a6d-3e2f1a0b4c5d",
  "name": "Support Widget",
  "status": "active",
  "session_flow_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
  "message_flow_id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
  "session_idle_timeout": 1800,
  "theme_config": {
    "primary_color": "#1a73e8",
    "secondary_color": "#f5f5f5",
    "header_background_color": "#1a73e8",
    "header_text_color": "#ffffff",
    "logo_url": "https://cdn.example.com/logo.png",
    "position": "bottom_right",
    "theme_mode": "light",
    "header_title": "Support",
    "header_subtitle": "We usually reply in a few minutes",
    "connecting_indicator_enabled": true,
    "connecting_indicator_text": "Connecting…",
    "typing_indicator_enabled": true,
    "border_radius": "rounded",
    "font_size": "default"
  },
  "direct_hash": "a8f3b2c1d4e5",
  "tm_create": "2026-01-15T09:30:00.000000Z",
  "tm_update": "2026-01-15T09:30:00.000000Z",
  "tm_delete": "2026-01-15T09:30:00.000000Z"
}