# Conversations

These endpoints only work for **verified** visitors. A plain user id is not enough; you must send the signed proof described in [Authentication](/docs/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.

```json
{
  "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.

```json
{
  "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
```

```json
{ "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.