# Conversation events

> conversation.started, message.sent and conversation.ended.

Source: https://www.hey.support/docs/webhooks/events/conversation

---

## `conversation.started`

Fires once, when a visitor's first message creates a conversation. It does not fire when a visitor resumes an existing one.

```json
{
  "conversation": {
    "id": 8214,
    "chatbot_id": 17,
    "visitor_id": "v_9f21…",
    "status": "ai",
    "created_at": "2026-08-26T10:00:00.000Z"
  }
}
```

`status` is `ai` at this point by definition — a conversation cannot start already handed off.

## `message.sent`

Fires for each message added to a conversation, from either side.

```json
{
  "conversation_id": 8214,
  "chatbot_id": 17,
  "message": {
    "id": 55129,
    "role": "user",
    "content": "Do you ship to Ireland?",
    "created_at": "2026-08-26T10:00:01.000Z"
  }
}
```

`role` is `user` for the visitor and `assistant` for the agent. Internal notes are **not** delivered — they are private to your team, so a note added in the Inbox never reaches your endpoint.

<Callout>
  This is the highest-volume event by a wide margin: a busy agent fires two per exchange. Subscribe to it only if you actually need message-level data — for "a conversation happened", `conversation.ended` is one event instead of dozens.
</Callout>

## `conversation.ended`

Fires when a conversation is resolved, by the visitor or by an operator.

```json
{
  "conversation": {
    "id": 8214,
    "chatbot_id": 17,
    "visitor_id": "v_9f21…",
    "previous_status": "ai",
    "message_count": 6,
    "is_lead": true
  }
}
```

`previous_status` tells you what it was before resolution — `ai`, `human_active` or `pending_handoff` — which is how you distinguish a conversation the agent finished from one a person had to take.

`is_lead` reflects whether contact details were captured at any point.