Documentation

Webhook events

Reference for all events your webhook can receive.

Chat events

`chat.created`

Fired when a visitor starts a new chat.

{
  "event": "chat.created",
  "timestamp": "2025-01-15T08:30:00.000Z",
  "organizationId": "clxyz1234567890",
  "data": {
    "chatId": "clxyz_chat_001",
    "visitorId": "visitor_abc123",
    "metadata": {
      "page": "https://example.com/pricing",
      "userAgent": "Mozilla/5.0..."
    }
  }
}

`chat.accepted`

Fired when an agent accepts a queued chat.

{
  "event": "chat.accepted",
  "timestamp": "2025-01-15T08:31:00.000Z",
  "organizationId": "clxyz1234567890",
  "data": {
    "chatId": "clxyz_chat_001",
    "agentId": "agent_456"
  }
}

`chat.closed`

Fired when a chat is closed by an agent or the system.

{
  "event": "chat.closed",
  "timestamp": "2025-01-15T09:15:00.000Z",
  "organizationId": "clxyz1234567890",
  "data": {
    "chatId": "clxyz_chat_001",
    "closedBy": "agent_456",
    "reason": "resolved"
  }
}

`chat.transferred`

Fired when a chat is transferred to another agent or group.

{
  "event": "chat.transferred",
  "timestamp": "2025-01-15T08:45:00.000Z",
  "organizationId": "clxyz1234567890",
  "data": {
    "chatId": "clxyz_chat_001",
    "fromAgentId": "agent_456",
    "toGroupId": "group_support_tier2",
    "reason": "escalation"
  }
}

`chat.rated`

Fired when a visitor rates a chat.

{
  "event": "chat.rated",
  "timestamp": "2025-01-15T09:20:00.000Z",
  "organizationId": "clxyz1234567890",
  "data": {
    "chatId": "clxyz_chat_001",
    "rating": 5,
    "comment": "Very helpful, thank you!"
  }
}

Message events

`message.sent`

Fired when a new message is sent in a chat.

{
  "event": "message.sent",
  "timestamp": "2025-01-15T08:32:00.000Z",
  "organizationId": "clxyz1234567890",
  "data": {
    "chatId": "clxyz_chat_001",
    "messageId": "msg_789",
    "content": "Hello, how can I help you today?",
    "senderType": "AGENT"
  }
}

Agent events

`agent.online`

Fired when an agent comes online.

{
  "event": "agent.online",
  "timestamp": "2025-01-15T08:00:00.000Z",
  "organizationId": "clxyz1234567890",
  "data": {
    "agentId": "agent_456",
    "timestamp": "2025-01-15T08:00:00.000Z"
  }
}

`agent.offline`

Fired when an agent goes offline.

{
  "event": "agent.offline",
  "timestamp": "2025-01-15T18:00:00.000Z",
  "organizationId": "clxyz1234567890",
  "data": {
    "agentId": "agent_456",
    "timestamp": "2025-01-15T18:00:00.000Z"
  }
}

`agent.status_changed`

Fired when an agent's status changes.

{
  "event": "agent.status_changed",
  "timestamp": "2025-01-15T12:00:00.000Z",
  "organizationId": "clxyz1234567890",
  "data": {
    "agentId": "agent_456",
    "oldStatus": "ONLINE",
    "newStatus": "AWAY"
  }
}

Visitor events

`visitor.started_typing`

Fired when a visitor begins typing in the chat widget.

{
  "event": "visitor.started_typing",
  "timestamp": "2025-01-15T08:31:30.000Z",
  "organizationId": "clxyz1234567890",
  "data": {
    "chatId": "clxyz_chat_001",
    "visitorId": "visitor_abc123"
  }
}

`visitor.page_visited`

Fired when a tracked visitor navigates to a new page.

{
  "event": "visitor.page_visited",
  "timestamp": "2025-01-15T08:29:00.000Z",
  "organizationId": "clxyz1234567890",
  "data": {
    "visitorId": "visitor_abc123",
    "url": "https://example.com/pricing",
    "title": "Pricing — Example"
  }
}

Selective subscription — You can subscribe to individual events or all events. Subscribing only to events you need reduces noise and improves performance.

Webhooks overview Signatures