# conversation.ended webhook

> The conversation.ended webhook: a chat with the AI waiter in your app ended, resolved, idle, restarted or logged out.

Source: https://tamr.link/docs/webhooks/conversation-ended

A chat in your app ended: staff marked it resolved (`resolved`), the diner went quiet (`idle`), started a new chat (`new_chat`) or logged out of your app (`logged_out`). Escalating to staff is not an end: the conversation stays open for them.

**A conversation can end more than once.** One closed as idle carries on when the diner writes again in the same sitting, and one staff resolved can carry on too. Each end is its own event with its own `webhook-id`: keep the one with the latest `endedAt`. For the transcript, call [Get a conversation](https://tamr.link/docs/api/get-conversation) with the diner's session.

## The `data` object

| Field | Type | Description |
| --- | --- | --- |
| `conversationId` | string | 1 to 200 characters. |
| `appKeyId` | string | 1 to 200 characters. |
| `externalUserId` | string or null | 1 to 200 characters. |
| `branch` | string or null | An address: lower-case letters, digits and dashes. |
| `reason` | string | One of `resolved`, `idle`, `new_chat`, `logged_out`, `unknown`. An open list: read a value you don't know as `unknown`. |
| `startedAt` | string (date-time) |  |
| `endedAt` | string (date-time) |  |
| `staffCalled` | boolean |  |
| `messageCount` | integer | 0 to 9,007,199,254,740,991. |

## Examples

conversation.ended:

```json
{
  "type": "conversation.ended",
  "timestamp": "2026-11-02T19:42:10.000Z",
  "livemode": true,
  "data": {
    "conversationId": "conv_0001",
    "appKeyId": "key_01",
    "externalUserId": "user-88213",
    "branch": "achrafieh",
    "reason": "resolved",
    "startedAt": "2026-11-02T19:05:00.000Z",
    "endedAt": "2026-11-02T19:42:10.000Z",
    "staffCalled": true,
    "messageCount": 14
  }
}
```

A guest on a test key, gone quiet.

conversation.ended:

```json
{
  "type": "conversation.ended",
  "timestamp": "2026-11-02T20:15:00.000Z",
  "livemode": false,
  "data": {
    "conversationId": "conv_0002",
    "appKeyId": "key_02",
    "externalUserId": null,
    "branch": null,
    "reason": "idle",
    "startedAt": "2026-11-02T19:58:00.000Z",
    "endedAt": "2026-11-02T20:15:00.000Z",
    "staffCalled": false,
    "messageCount": 3
  }
}
```

A reason from a newer server reads as unknown.

conversation.ended:

```json
{
  "type": "conversation.ended",
  "timestamp": "2026-11-02T21:00:00.000Z",
  "livemode": true,
  "data": {
    "conversationId": "conv_0003",
    "appKeyId": "key_01",
    "externalUserId": "user-1",
    "branch": "achrafieh",
    "reason": "closed_by_host",
    "startedAt": "2026-11-02T20:30:00.000Z",
    "endedAt": "2026-11-02T21:00:00.000Z",
    "staffCalled": false,
    "messageCount": 0
  }
}
```

The diner logged out of the app (identity.clear, #645).

conversation.ended:

```json
{
  "type": "conversation.ended",
  "timestamp": "2026-11-02T20:40:00.000Z",
  "livemode": true,
  "data": {
    "conversationId": "conv_0004",
    "appKeyId": "key_01",
    "externalUserId": "user-88213",
    "branch": "achrafieh",
    "reason": "logged_out",
    "startedAt": "2026-11-02T20:20:00.000Z",
    "endedAt": "2026-11-02T20:40:00.000Z",
    "staffCalled": false,
    "messageCount": 6
  }
}
```

## A test event

What **Send a test event** in the dashboard sends: `livemode: false`, and every id starting `test_`.

conversation.ended, test:

```json
{
  "type": "conversation.ended",
  "timestamp": "2026-11-16T12:00:00.000Z",
  "livemode": false,
  "data": {
    "conversationId": "test_conversation",
    "appKeyId": "test_app_key",
    "externalUserId": "test_user",
    "branch": null,
    "reason": "resolved",
    "startedAt": "2026-11-16T11:40:00.000Z",
    "endedAt": "2026-11-16T12:00:00.000Z",
    "staffCalled": false,
    "messageCount": 6
  }
}
```
