Conversations

These endpoints only work for verified visitors. A plain user id is not enough; you must send the signed proof described in Authentication.

/api/v1/{organisation}/widgets/{widget}/conversations

Auth: widget that supports chat, plus signed identity on every call.

Send identity as query parameters on GET/DELETE, or in the JSON body on PUT:

Field	Description
user	Your visitor's id
hash	HMAC-SHA256(user, signing_secret) as a hex string

---

List conversations

GET /conversations?user=…&hash=…

Returns up to 50 conversations for that verified visitor on this widget, newest first.

{
  "data": [
    {
      "conversation_id": "…",
      "title": "Pricing questions",
      "kept": false,
      "last_message_at": "2026-07-01T12:00:00+00:00"
    }
  ]
}

---

Get a transcript

GET /conversations/{conversationId}?user=…&hash=…

Only visitor and assistant messages are returned.

{
  "data": {
    "conversation_id": "…",
    "kept": false,
    "messages": [
      { "role": "user", "text": "How does pricing work?", "created_at": "…" },
      { "role": "assistant", "text": "…", "created_at": "…" }
    ]
  }
}

Conversations that do not belong to this visitor return 404.

---

Keep or release

PUT /conversations/{conversationId}/keep

{ "kept": true, "user": "…", "hash": "…" }

Kept conversations are not removed by automatic retention. There is a limit per visitor; if it is reached, the API returns 422.

---

Delete one conversation

DELETE /conversations/{conversationId}?user=…&hash=…

204 No Content. Removes the transcript and metadata, including kept conversations. Keep never blocks a visitor deleting their own history.

---

Delete all conversations

DELETE /conversations?user=…&hash=…

204 No Content. Removes every verified conversation for that visitor on this widget.