Chat widgets
The embeddable chat widget: its configuration, conversations and captured leads.
List chat widgets
Returns the workspace's widgets. widget_key is the public embed key — it identifies the widget in the snippet on your site and is not a secret.
Requires the module-chat-widget license feature. Without it the request is refused with 403 license_required — see plans and modules.
query Parameters
cursor^[A-Za-z0-9_-]+$limitoffsetsort^-?[a-z0-9_]+$Headers
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
List chat widgets › Responses
Success
has_moreWhether more rows exist past this page.
next_cursorPass back as cursor for the next page. Null on the last page.
Create a chat widget
The agent behind a widget must be marked public-facing — a widget is an anonymous surface, and an internal agent is not written to be one, so this refuses rather than exposing it.
widget_origins is the list of sites allowed to embed it.
Requires the module-chat-widget license feature. Without it the request is refused with 403 license_required — see plans and modules.
Headers
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
Create a chat widget › Request Body
widget_namewidget_agentwidget_originswidget_welcomewidget_themewidget_configwidget_limitsCreate a chat widget › Responses
Created
widget_idwidget_activewidget_createdwidget_updatedwidget_created_bywidget_keywidget_namewidget_agentwidget_originswidget_welcomewidget_themewidget_configwidget_limitsGet a chat widget
Returns the widget with the agent behind it, its origin allowlist and its theme.
Requires the module-chat-widget license feature. Without it the request is refused with 403 license_required — see plans and modules.
path Parameters
idHeaders
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
Get a chat widget › Responses
Success
widget_idwidget_activewidget_createdwidget_updatedwidget_created_bywidget_keywidget_namewidget_agentwidget_originswidget_welcomewidget_themewidget_configwidget_limitsDelete a chat widget
Soft delete: the widget stops answering on the sites embedding it. Its conversations and captured leads are kept.
Requires the module-chat-widget license feature. Without it the request is refused with 403 license_required — see plans and modules.
path Parameters
idHeaders
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
Delete a chat widget › Responses
Success. No content.
Update a chat widget
Applies the widget_-prefixed fields present in the body. Changing the origin allowlist takes effect on the next page load; sessions already open are unaffected.
Requires the module-chat-widget license feature. Without it the request is refused with 403 license_required — see plans and modules.
path Parameters
idHeaders
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
Update a chat widget › Request Body optional
widget_namewidget_activewidget_agentwidget_originswidget_welcomewidget_themewidget_configwidget_limitsUpdate a chat widget › Responses
Success
widget_idwidget_activewidget_createdwidget_updatedwidget_created_bywidget_keywidget_namewidget_agentwidget_originswidget_welcomewidget_themewidget_configwidget_limitsGet widget statistics
Conversation and lead counts over the last days (30 by default), with the average, median and longest conversation length.
Requires the module-chat-widget license feature. Without it the request is refused with 403 license_required — see plans and modules.
path Parameters
idquery Parameters
daysHeaders
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
Get widget statistics › Responses
Success
Get a preview link
A link that opens the widget on a page of its own, outside any website, for trying it out. It skips the origin allowlist and stops opening conversations after expires_in seconds; the conversations it starts carry preview: true in their wses_metadata.
Requires the module-chat-widget license feature. Without it the request is refused with 403 license_required — see plans and modules.
path Parameters
idHeaders
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
Get a preview link › Responses
Success
urlexpires_inSeconds the link stays valid.
List conversations
Newest first. has_messages=true skips sessions where the visitor never wrote, leads_only=true keeps only the conversations that captured contact details, downvoted_only=true only those with an answer rated not helpful, and q searches what was said.
Requires the module-chat-widget license feature. Without it the request is refused with 403 license_required — see plans and modules.
path Parameters
idquery Parameters
cursor^[A-Za-z0-9_-]+$downvoted_onlyhas_messagesleads_onlylimitoffsetqsort^-?[a-z0-9_]+$wses_createdHeaders
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
List conversations › Responses
Success
has_moreWhether more rows exist past this page.
next_cursorPass back as cursor for the next page. Null on the last page.
Get a conversation
The captured contact details together with the conversation they came from.
Requires the module-chat-widget license feature. Without it the request is refused with 403 license_required — see plans and modules.
path Parameters
idHeaders
X-Tenant-IdThe workspace this request acts in. Every row the API returns is isolated to it at the database layer by row-level security.
Get a conversation › Responses
Success