Conversation events

Three events follow a conversation from its first message to its resolution. The envelope is described in the overview.

conversation.started

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

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

status is always ai here: a conversation cannot start already handed off.

message.sent

Fires for each message added to a conversation, from either side. role is user for the visitor and assistant for the agent; internal notes are never delivered.

{
  "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"
  }
}

conversation.ended

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

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

previous_status is ai, human_active or pending_handoff, which is how you tell a conversation the agent finished from one a person had to take. is_lead says whether contact details were captured at any point.

Next steps