conversation.ended webhook

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

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 with the diner's session.

The data object

FieldTypeDescription
conversationIdstring1 to 200 characters.
appKeyIdstring1 to 200 characters.
externalUserIdstring or null1 to 200 characters.
branchstring or nullAn address: lower-case letters, digits and dashes.
reasonstringOne of resolved, idle, new_chat, logged_out, unknown. An open list: read a value you don't know as unknown.
startedAtstring (date-time)
endedAtstring (date-time)
staffCalledboolean
messageCountinteger0 to 9,007,199,254,740,991.

Examples

conversation.ended
{
  "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
{
  "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
{
  "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
{
  "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
{
  "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
  }
}