Widgets API

Widgets belong to the bearer client’s project. This API can list, create and change the supported widget settings; it does not delete widgets.

Widget object

Successful widget methods return this shape:

{
  "id": "wdg_abc",
  "name": "Support assistant",
  "code": "Yq4X8qk3",
  "is_enabled": true,
  "suggestions_enabled": false,
  "trigger_templates": ["How can I help?"],
  "appearance": {"position": "right"}
}

Field	Description
id	Widget ID for management methods.
code	Generated public widget code used when installing the widget.
is_enabled	Whether the widget is enabled.
suggestions_enabled	Whether the widget displays suggested next questions.
trigger_templates	Configured suggestions available for trigger resolution.
appearance	The widget’s current appearance configuration.

List widgets

GET /api/widgets
Authorization: Bearer CLIENT_ID.CLIENT_SECRET

200 OK:

{
  "items": [
    {
      "id": "wdg_abc",
      "name": "Support assistant",
      "code": "Yq4X8qk3",
      "is_enabled": true,
      "suggestions_enabled": false,
      "trigger_templates": [
        "How can I help?"
      ],
      "appearance": {
        "position": "right"
      }
    }
  ]
}

Create a widget

POST /api/widgets
Authorization: Bearer CLIENT_ID.CLIENT_SECRET
Content-Type: application/json

{
  "name": "Support assistant"
}

JSON field	Required	Rules
name	Yes	Non-empty string, maximum 128 characters.

201 Created returns the widget object, including its generated id and code. Default prompts, trigger templates and appearance are taken from the project’s widget defaults.

Read a widget

GET /api/widgets/{widget_id}
Authorization: Bearer CLIENT_ID.CLIENT_SECRET

Path parameter	Description
widget_id	The id returned by the list or create method.

200 OK returns one widget object. An unknown ID or a widget in another project returns 404.

Update a widget

PATCH /api/widgets/{widget_id}
Authorization: Bearer CLIENT_ID.CLIENT_SECRET
Content-Type: application/json

{
  "name": "Website support",
  "is_enabled": true,
  "suggestions_enabled": false
}

All body fields are optional; send only the values that need changing.

JSON field	Type	Rules
name	string	Non-empty, maximum 128 characters.
is_enabled	boolean	Enables or disables the widget.
suggestions_enabled	boolean	Enables or disables widget suggestions.

200 OK returns the complete updated widget object. Other widget settings, including public code, prompts, templates and appearance, are not writable by this API.

Resolve page triggers

This endpoint is used by an installed public widget to obtain suggestions for the page a visitor is viewing. It deliberately has no bearer token because the request originates in the visitor’s browser.

GET /api/triggers/resolve?code=Yq4X8qk3&url=https%3A%2F%2Fexample.com%2Fhelp%2F&title=Help%20centre

Query parameter	Required	Description
code	Yes	Public widget code, 1–128 characters.
url	No	URL of the visitor’s current page. Defaults to an empty string.
title	No	Page title supplied by the widget. Defaults to an empty string.

200 OK:

{
  "triggers": [
    {
      "key": "shipping",
      "text": "How long does shipping take?"
    }
  ],
  "page_token": "signed-token-or-null"
}

triggers can be empty. page_token is null when no matching indexed page provides one; otherwise the widget uses it in its next request.