curl --silent --show-error --fail-with-body --request POST \
--url 'https://api.example.com/api/response/threads' \
--header 'x-widget-token: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"subject": "New conversation",
"message": "Two-person tent, green — replacement for damaged pole set.",
"channel": "chat",
"meta": {
"sessionId": "string",
"threadMessages": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"sender": "user",
"text": "Two-person tent, green — replacement for damaged pole set.",
"timestamp": "2026-08-31T14:22:05Z"
}
]
},
"provider": "openai",
"attachments": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Two-Person Tent",
"size": 1,
"type": "standard",
"dataUrl": "string",
"previewUrl": "string",
"url": "https://example.com/webhooks/stateset"
}
]
}'
{
"threadId": "string",
"threadToken": "YOUR_API_KEY",
"thread": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"subject": "Replacement tent pole set",
"title": "Replacement tent pole set",
"channel": "string",
"meta": {},
"provider": "openai",
"createdAt": "2026-08-31T14:22:05Z",
"updatedAt": "2026-08-31T14:22:05Z",
"messages": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"sender": "user",
"text": "Two-person tent, green — replacement for damaged pole set.",
"timestamp": "2026-08-31T14:22:05Z",
"type": "text",
"richContent": {
"image": "https://cdn.example.com/products/tent-2p.jpg",
"title": "Replacement tent pole set",
"description": "Two-person tent, green — replacement for damaged pole set.",
"formId": "string",
"buttonStyle": "default",
"layout": "scroll",
"actions": [
{
"label": null
}
],
"buttons": [
{
"label": null,
"value": null,
"href": null,
"target": null
}
],
"fields": [
{
"name": null,
"label": null,
"type": null,
"placeholder": null,
"required": null,
"options": null
}
],
"submitLabel": "string",
"headline": "Replacement tent pole set",
"subhead": "string",
"products": [
{
"id": null,
"title": null,
"price": null,
"image": null,
"url": null,
"description": null,
"whyItMatches": null,
"rating": null,
"reviewCount": null,
"badges": null,
"isUpsell": null,
"actions": null,
"variantOptions": null,
"variantSelectionLabel": null,
"variantSelectionPlaceholder": null,
"variantSelectionRequired": null,
"variantDisplay": null,
"selectedVariantId": null,
"selectedVariantLabel": null,
"complementaryProducts": null,
"complementaryHeadline": null,
"complementaryText": null,
"continueShoppingAfterAdd": null
}
],
"autoAction": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"type": "add_to_cart",
"productId": "string",
"quantity": 2,
"expiresAt": "2026-08-31T14:22:05Z"
},
"orders": [
{
"id": null,
"name": null,
"amount": null,
"status": null,
"trackingUrl": null,
"lineItems": null,
"actions": null
}
]
},
"attachments": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Two-Person Tent",
"size": 1,
"type": "standard",
"dataUrl": "string",
"previewUrl": "string",
"url": "https://example.com/webhooks/stateset"
}
],
"toolCalls": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Two-Person Tent",
"arguments": {},
"result": null,
"status": "running"
}
],
"sources": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"title": "Replacement tent pole set",
"url": "https://example.com/webhooks/stateset",
"snippet": "string"
}
],
"suggestions": [
"string"
],
"thinking": "string",
"reaction": "up",
"feedbackComment": "string",
"feedbackAt": "2026-08-31T14:22:05Z",
"authorName": "string",
"operatorEvent": "joined"
}
]
}
}
Alias of POST /api/threads
Widget identity is verified when signing is configured; tokenless compatibility does not establish tenant ownership…
POST
/
api
/
response
/
threads
curl --silent --show-error --fail-with-body --request POST \
--url 'https://api.example.com/api/response/threads' \
--header 'x-widget-token: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"subject": "New conversation",
"message": "Two-person tent, green — replacement for damaged pole set.",
"channel": "chat",
"meta": {
"sessionId": "string",
"threadMessages": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"sender": "user",
"text": "Two-person tent, green — replacement for damaged pole set.",
"timestamp": "2026-08-31T14:22:05Z"
}
]
},
"provider": "openai",
"attachments": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Two-Person Tent",
"size": 1,
"type": "standard",
"dataUrl": "string",
"previewUrl": "string",
"url": "https://example.com/webhooks/stateset"
}
]
}'
{
"threadId": "string",
"threadToken": "YOUR_API_KEY",
"thread": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"subject": "Replacement tent pole set",
"title": "Replacement tent pole set",
"channel": "string",
"meta": {},
"provider": "openai",
"createdAt": "2026-08-31T14:22:05Z",
"updatedAt": "2026-08-31T14:22:05Z",
"messages": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"sender": "user",
"text": "Two-person tent, green — replacement for damaged pole set.",
"timestamp": "2026-08-31T14:22:05Z",
"type": "text",
"richContent": {
"image": "https://cdn.example.com/products/tent-2p.jpg",
"title": "Replacement tent pole set",
"description": "Two-person tent, green — replacement for damaged pole set.",
"formId": "string",
"buttonStyle": "default",
"layout": "scroll",
"actions": [
{
"label": null
}
],
"buttons": [
{
"label": null,
"value": null,
"href": null,
"target": null
}
],
"fields": [
{
"name": null,
"label": null,
"type": null,
"placeholder": null,
"required": null,
"options": null
}
],
"submitLabel": "string",
"headline": "Replacement tent pole set",
"subhead": "string",
"products": [
{
"id": null,
"title": null,
"price": null,
"image": null,
"url": null,
"description": null,
"whyItMatches": null,
"rating": null,
"reviewCount": null,
"badges": null,
"isUpsell": null,
"actions": null,
"variantOptions": null,
"variantSelectionLabel": null,
"variantSelectionPlaceholder": null,
"variantSelectionRequired": null,
"variantDisplay": null,
"selectedVariantId": null,
"selectedVariantLabel": null,
"complementaryProducts": null,
"complementaryHeadline": null,
"complementaryText": null,
"continueShoppingAfterAdd": null
}
],
"autoAction": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"type": "add_to_cart",
"productId": "string",
"quantity": 2,
"expiresAt": "2026-08-31T14:22:05Z"
},
"orders": [
{
"id": null,
"name": null,
"amount": null,
"status": null,
"trackingUrl": null,
"lineItems": null,
"actions": null
}
]
},
"attachments": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Two-Person Tent",
"size": 1,
"type": "standard",
"dataUrl": "string",
"previewUrl": "string",
"url": "https://example.com/webhooks/stateset"
}
],
"toolCalls": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Two-Person Tent",
"arguments": {},
"result": null,
"status": "running"
}
],
"sources": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"title": "Replacement tent pole set",
"url": "https://example.com/webhooks/stateset",
"snippet": "string"
}
],
"suggestions": [
"string"
],
"thinking": "string",
"reaction": "up",
"feedbackComment": "string",
"feedbackAt": "2026-08-31T14:22:05Z",
"authorName": "string",
"operatorEvent": "joined"
}
]
}
}
Widget identity is verified when signing is configured; tokenless compatibility does not establish tenant ownership. See the authentication and recovery guide for credential and retry rules.
Request body
ThreadCreateRequest
Free-form request metadata forwarded to the agent (department, custom fields, page context,
sessionId, and agent/agentConfig/kb identity hints). Stored on the thread. Shape is merchant-defined.Response
object
Thread as serialized for clients: server-only fields (
state, accessToken, owner, restoredFromClientHistory) are stripped.Show Thread
Show Thread
Show Message
Show Message
Allowed values:
'text', 'tool_call', 'tool_result', 'card', 'buttons', 'form', 'product_cards', 'order_cards', 'citation', 'thinking'.Payload of a rich message (
card, buttons, form, product_cards, order_cards); which keys are present depends on the message type. Mirrors RichContent in src/types/messages.ts minus client-only callbacks.Status codes
| Code | Meaning |
|---|---|
201 | Thread created; threadToken is disclosed only here. |
401 | Widget token missing, malformed, expired, from the future, or badly signed |
403 | Request org/agent disagrees with the widget token claims |
429 | Too many requests for this IP (scoped by verified org/agent) |
500 | Unhandled error |
Using this contract
Read the source OpenAPI document for declared schemas and alternatives. This page also includes documented corrections from the spec overlays. Example IDs and values are illustrative; replace them with records from your workspace.curl --silent --show-error --fail-with-body --request POST \
--url 'https://api.example.com/api/response/threads' \
--header 'x-widget-token: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"subject": "New conversation",
"message": "Two-person tent, green — replacement for damaged pole set.",
"channel": "chat",
"meta": {
"sessionId": "string",
"threadMessages": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"sender": "user",
"text": "Two-person tent, green — replacement for damaged pole set.",
"timestamp": "2026-08-31T14:22:05Z"
}
]
},
"provider": "openai",
"attachments": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Two-Person Tent",
"size": 1,
"type": "standard",
"dataUrl": "string",
"previewUrl": "string",
"url": "https://example.com/webhooks/stateset"
}
]
}'
{
"threadId": "string",
"threadToken": "YOUR_API_KEY",
"thread": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"subject": "Replacement tent pole set",
"title": "Replacement tent pole set",
"channel": "string",
"meta": {},
"provider": "openai",
"createdAt": "2026-08-31T14:22:05Z",
"updatedAt": "2026-08-31T14:22:05Z",
"messages": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"sender": "user",
"text": "Two-person tent, green — replacement for damaged pole set.",
"timestamp": "2026-08-31T14:22:05Z",
"type": "text",
"richContent": {
"image": "https://cdn.example.com/products/tent-2p.jpg",
"title": "Replacement tent pole set",
"description": "Two-person tent, green — replacement for damaged pole set.",
"formId": "string",
"buttonStyle": "default",
"layout": "scroll",
"actions": [
{
"label": null
}
],
"buttons": [
{
"label": null,
"value": null,
"href": null,
"target": null
}
],
"fields": [
{
"name": null,
"label": null,
"type": null,
"placeholder": null,
"required": null,
"options": null
}
],
"submitLabel": "string",
"headline": "Replacement tent pole set",
"subhead": "string",
"products": [
{
"id": null,
"title": null,
"price": null,
"image": null,
"url": null,
"description": null,
"whyItMatches": null,
"rating": null,
"reviewCount": null,
"badges": null,
"isUpsell": null,
"actions": null,
"variantOptions": null,
"variantSelectionLabel": null,
"variantSelectionPlaceholder": null,
"variantSelectionRequired": null,
"variantDisplay": null,
"selectedVariantId": null,
"selectedVariantLabel": null,
"complementaryProducts": null,
"complementaryHeadline": null,
"complementaryText": null,
"continueShoppingAfterAdd": null
}
],
"autoAction": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"type": "add_to_cart",
"productId": "string",
"quantity": 2,
"expiresAt": "2026-08-31T14:22:05Z"
},
"orders": [
{
"id": null,
"name": null,
"amount": null,
"status": null,
"trackingUrl": null,
"lineItems": null,
"actions": null
}
]
},
"attachments": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Two-Person Tent",
"size": 1,
"type": "standard",
"dataUrl": "string",
"previewUrl": "string",
"url": "https://example.com/webhooks/stateset"
}
],
"toolCalls": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Two-Person Tent",
"arguments": {},
"result": null,
"status": "running"
}
],
"sources": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"title": "Replacement tent pole set",
"url": "https://example.com/webhooks/stateset",
"snippet": "string"
}
],
"suggestions": [
"string"
],
"thinking": "string",
"reaction": "up",
"feedbackComment": "string",
"feedbackAt": "2026-08-31T14:22:05Z",
"authorName": "string",
"operatorEvent": "joined"
}
]
}
}
Last modified on November 13, 2026