curl --silent --show-error --fail-with-body --request PATCH \
--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' \
--header 'Content-Type: application/json' \
--data '{
"subject": "Replacement tent pole set",
"title": "Replacement tent pole set",
"meta": {}
}'
{
"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 PATCH /api/threads/{id}
For an existing protected thread, send its x-widget-thread-token capability in addition to widget identity…
PATCH
/
api
/
response
/
threads
/
{id}
curl --silent --show-error --fail-with-body --request PATCH \
--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' \
--header 'Content-Type: application/json' \
--data '{
"subject": "Replacement tent pole set",
"title": "Replacement tent pole set",
"meta": {}
}'
{
"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"
}
]
}
}
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.
Request body
ThreadUpdateRequest
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 |
|---|---|
200 | Updated thread |
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 PATCH \
--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' \
--header 'Content-Type: application/json' \
--data '{
"subject": "Replacement tent pole set",
"title": "Replacement tent pole set",
"meta": {}
}'
{
"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