curl --silent --show-error --fail-with-body --request GET \
--url 'https://api.example.com/api/response/threads/{id}' \
--header 'x-widget-token: YOUR_API_KEY' \
--header 'x-widget-thread-token: REPLACE_WITH_X_WIDGET_THREAD_TOKEN'
{
"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"
}
]
},
"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": "Replacement tent pole set"
}
],
"buttons": [
{
"label": "Replacement tent pole set",
"value": "49.00",
"href": "https://example.com/webhooks/stateset",
"target": "_self"
}
],
"fields": [
{
"name": "Two-Person Tent",
"label": "Replacement tent pole set",
"type": "standard",
"placeholder": "string",
"required": true,
"options": []
}
],
"submitLabel": "string",
"headline": "Replacement tent pole set",
"subhead": "string",
"products": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"title": "Replacement tent pole set",
"price": "49.00",
"image": "https://cdn.example.com/products/tent-2p.jpg",
"url": "https://example.com/webhooks/stateset",
"description": "Two-person tent, green — replacement for damaged pole set.",
"whyItMatches": "string",
"rating": 1.5,
"reviewCount": 1,
"badges": [],
"isUpsell": true,
"actions": [],
"variantOptions": [],
"variantSelectionLabel": "string",
"variantSelectionPlaceholder": "string",
"variantSelectionRequired": true,
"variantDisplay": "select",
"selectedVariantId": "string",
"selectedVariantLabel": "string",
"complementaryProducts": [],
"complementaryHeadline": "string",
"complementaryText": "string",
"continueShoppingAfterAdd": true
}
],
"autoAction": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"type": "add_to_cart",
"productId": "string",
"quantity": 2,
"expiresAt": "2026-08-31T14:22:05Z"
},
"orders": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Two-Person Tent",
"amount": "49.00",
"status": "pending",
"trackingUrl": "string",
"lineItems": [],
"actions": []
}
]
},
"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"
}
],
"escalated": true
}
Alias of GET /api/threads/{id}
For an existing protected thread, send its x-widget-thread-token capability in addition to widget identity…
GET
/
api
/
response
/
threads
/
{id}
curl --silent --show-error --fail-with-body --request GET \
--url 'https://api.example.com/api/response/threads/{id}' \
--header 'x-widget-token: YOUR_API_KEY' \
--header 'x-widget-thread-token: REPLACE_WITH_X_WIDGET_THREAD_TOKEN'
{
"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"
}
]
},
"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": "Replacement tent pole set"
}
],
"buttons": [
{
"label": "Replacement tent pole set",
"value": "49.00",
"href": "https://example.com/webhooks/stateset",
"target": "_self"
}
],
"fields": [
{
"name": "Two-Person Tent",
"label": "Replacement tent pole set",
"type": "standard",
"placeholder": "string",
"required": true,
"options": []
}
],
"submitLabel": "string",
"headline": "Replacement tent pole set",
"subhead": "string",
"products": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"title": "Replacement tent pole set",
"price": "49.00",
"image": "https://cdn.example.com/products/tent-2p.jpg",
"url": "https://example.com/webhooks/stateset",
"description": "Two-person tent, green — replacement for damaged pole set.",
"whyItMatches": "string",
"rating": 1.5,
"reviewCount": 1,
"badges": [],
"isUpsell": true,
"actions": [],
"variantOptions": [],
"variantSelectionLabel": "string",
"variantSelectionPlaceholder": "string",
"variantSelectionRequired": true,
"variantDisplay": "select",
"selectedVariantId": "string",
"selectedVariantLabel": "string",
"complementaryProducts": [],
"complementaryHeadline": "string",
"complementaryText": "string",
"continueShoppingAfterAdd": true
}
],
"autoAction": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"type": "add_to_cart",
"productId": "string",
"quantity": 2,
"expiresAt": "2026-08-31T14:22:05Z"
},
"orders": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Two-Person Tent",
"amount": "49.00",
"status": "pending",
"trackingUrl": "string",
"lineItems": [],
"actions": []
}
]
},
"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"
}
],
"escalated": true
}
For an existing protected thread, send its
x-widget-thread-token capability in addition to widget identity. 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.
Path parameters
Headers
Capability required for an existing thread that has an issued token. Legacy capability-less threads are denied when STATESET_THREAD_TOKEN_REQUIRED=true.
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.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 |
|---|---|
200 | Thread and its messages |
401 | Widget token missing, malformed, expired, from the future, or badly signed |
403 | Thread capability missing/wrong, thread owner mismatch, or token identity mismatch |
404 | Unknown thread (or, for feedback, a message that is not an assistant message) |
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 GET \
--url 'https://api.example.com/api/response/threads/{id}' \
--header 'x-widget-token: YOUR_API_KEY' \
--header 'x-widget-thread-token: REPLACE_WITH_X_WIDGET_THREAD_TOKEN'
{
"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"
}
]
},
"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": "Replacement tent pole set"
}
],
"buttons": [
{
"label": "Replacement tent pole set",
"value": "49.00",
"href": "https://example.com/webhooks/stateset",
"target": "_self"
}
],
"fields": [
{
"name": "Two-Person Tent",
"label": "Replacement tent pole set",
"type": "standard",
"placeholder": "string",
"required": true,
"options": []
}
],
"submitLabel": "string",
"headline": "Replacement tent pole set",
"subhead": "string",
"products": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"title": "Replacement tent pole set",
"price": "49.00",
"image": "https://cdn.example.com/products/tent-2p.jpg",
"url": "https://example.com/webhooks/stateset",
"description": "Two-person tent, green — replacement for damaged pole set.",
"whyItMatches": "string",
"rating": 1.5,
"reviewCount": 1,
"badges": [],
"isUpsell": true,
"actions": [],
"variantOptions": [],
"variantSelectionLabel": "string",
"variantSelectionPlaceholder": "string",
"variantSelectionRequired": true,
"variantDisplay": "select",
"selectedVariantId": "string",
"selectedVariantLabel": "string",
"complementaryProducts": [],
"complementaryHeadline": "string",
"complementaryText": "string",
"continueShoppingAfterAdd": true
}
],
"autoAction": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"type": "add_to_cart",
"productId": "string",
"quantity": 2,
"expiresAt": "2026-08-31T14:22:05Z"
},
"orders": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "Two-Person Tent",
"amount": "49.00",
"status": "pending",
"trackingUrl": "string",
"lineItems": [],
"actions": []
}
]
},
"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"
}
],
"escalated": true
}
Last modified on November 13, 2026