> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# React to an assistant message (thumbs up/down, optional comment)

> Only assistant (sender: ai) messages accept feedback; user messages and unknown ids answer 404 not_found so callers cannot tell them apart…

Only assistant (`sender: ai`) messages accept feedback; user messages and unknown ids
answer `404 not_found` so callers cannot tell them apart. `reaction: null` clears the
reaction and drops the comment. The thread persist is awaited; the Hasura mirror is
fire-and-forget.

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.

### Headers

**x-widget-thread-token** `string`

Capability for the thread containing the stored AI message being rated.

### Request body

`FeedbackRequest`

**threadId** `string` *required*

**messageId** `string` *required*

**reaction** `MessageReaction` *required*

Allowed values: `'up'`, `'down'`, `null`.

**comment** `string,null`

Only kept with a non-null reaction. Maximum length: `500`.

**threadToken** `string`

Alternative to the `x-widget-thread-token` header.

### Response

`object`

**ok** `boolean` *required*

Fixed value: `true`.

**threadId** `string` *required*

**messageId** `string` *required*

**reaction** `MessageReaction` *required*

Allowed values: `'up'`, `'down'`, `null`.

### Status codes

| Code | Meaning |
| - | - |
| `200` | Reaction stored |
| `400` | Body failed validation (missing ids, bad reaction, comment over 500 chars) |
| `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](https://docs.stateset.com/spec/chat-widget.json) for declared schemas and alternatives.
This page also includes documented corrections from the [spec overlays](https://github.com/stateset/docs/tree/main/spec/overlays).
Example IDs and values are illustrative; replace them with records from your workspace.

```bash cURL theme={null}
curl --silent --show-error --fail-with-body --request POST \
  --url 'https://api.example.com/api/response/feedback' \
  --header 'x-widget-token: YOUR_API_KEY' \
  --header 'x-widget-thread-token: REPLACE_WITH_X_WIDGET_THREAD_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "threadId": "string",
  "messageId": "string",
  "reaction": "up",
  "comment": "Two-person tent, green — replacement for damaged pole set.",
  "threadToken": "YOUR_API_KEY"
}'
```

```json 200 theme={null}
{
  "ok": true,
  "threadId": "string",
  "messageId": "string",
  "reaction": "up"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.