Chats and feedback API

The API reads history and visitor feedback from the bearer client’s project. Visitor identity is returned as an anonymized stable hash; internal context, provider diagnostics and secrets are not returned.

Chat object

{
  "id": "c6cf9f2e-25a4-4bf3-8b3d-e8cb52d85860",
  "created_at": "2026-09-11T09:00:00+00:00",
  "updated_at": "2026-09-11T09:02:00+00:00",
  "visitor": "34bc5f38478d2c89",
  "widget_code": "Yq4X8qk3",
  "feedback": {"vote": true, "comment": "Solved my problem"}
}

Field	Description
id	Chat ID used to fetch a chat or its messages.
created_at, updated_at	Chat timestamps, or null when unavailable.
visitor	A 16-character anonymized hash, not the visitor’s original identifier.
widget_code	Public code of the widget that opened the chat, or null.
feedback	Visitor feedback object, or null if no feedback was submitted.

List chat history

GET /api/chats?limit=50
Authorization: Bearer CLIENT_ID.CLIENT_SECRET

Query parameter	Required	Description
limit	No	Number of chats to return, from 1 to 100. Defaults to 50.

200 OK returns chats in reverse creation order:

{
  "items": [
    {
      "id": "c6cf9f2e-25a4-4bf3-8b3d-e8cb52d85860",
      "created_at": "2026-09-11T09:00:00+00:00",
      "updated_at": "2026-09-11T09:02:00+00:00",
      "visitor": "34bc5f38478d2c89",
      "widget_code": "Yq4X8qk3",
      "feedback": null
    }
  ]
}

Get one chat

GET /api/chats/{chat_id}
Authorization: Bearer CLIENT_ID.CLIENT_SECRET

Path parameter	Description
chat_id	The ID returned by GET /api/chats.

200 OK returns one chat object. An unknown ID or a chat outside the client’s project returns 404.

Read chat messages

GET /api/chats/{chat_id}/messages?limit=50
Authorization: Bearer CLIENT_ID.CLIENT_SECRET

Parameter	Required	Description
chat_id	Yes	Chat ID from the chat list.
limit	No	Number of messages to return, from 1 to 100. Defaults to 50.

200 OK returns messages in chronological order:

{
  "items": [
    {
      "id": 318,
      "role": "user",
      "text": "How long does shipping take?",
      "created_at": "2026-09-11T09:00:04+00:00",
      "vote": null,
      "guardrail_triggered": false,
      "guardrail_stage": null
    },
    {
      "id": 319,
      "role": "assistant",
      "text": "Standard shipping takes three to five business days.",
      "created_at": "2026-09-11T09:00:06+00:00",
      "vote": true,
      "guardrail_triggered": false,
      "guardrail_stage": null
    }
  ]
}

Field	Description
role	Message role as stored by the chat.
text	Visible message text.
vote	Message vote, or null when no vote exists.
guardrail_triggered	Whether a guardrail affected the message.
guardrail_stage	Guardrail stage, or null.

List feedback

GET /api/feedback?limit=50
Authorization: Bearer CLIENT_ID.CLIENT_SECRET

Query parameter	Required	Description
limit	No	Number of feedback-bearing chats to return, from 1 to 100. Defaults to 50.

200 OK returns the same items shape as the chat list, but includes only chats whose feedback is an object:

{
  "items": [
    {
      "id": "c6cf9f2e-25a4-4bf3-8b3d-e8cb52d85860",
      "created_at": "2026-09-11T09:00:00+00:00",
      "updated_at": "2026-09-11T09:02:00+00:00",
      "visitor": "34bc5f38478d2c89",
      "widget_code": "Yq4X8qk3",
      "feedback": {"vote": true, "comment": "Solved my problem"}
    }
  ]
}

Connecting an external operator to a live chat over WebSocket is not part of this API. It remains a separate operator-handoff API requirement.