Skip to content

Webhook events

Every webhook event Vocenya sends, the scope each one needs and an example payload for each.

Subscribe an endpoint to the events you need. Each event needs your key's webhooks:manage scope plus the read scope of its record. All events share the envelope {"id", "type", "livemode", "created_at", "data"} described in Webhooks; data differs per event.

Event When it is sent Scopes needed to subscribe
lead.created A lead was captured leads:read
call.completed An inbound call ended calls:read
booking.created An appointment was booked bookings:read
chat.handed_off A website chat was handed to a person chats:read
outbound_call.completed An outbound call ended outbound:read
chat.started A visitor started a website chat chats:read
chat.message.created A website chat got a new message chats:read
chat.lead_captured A website chat captured a lead chats:read, leads:read
chat.handoff_requested The visitor or the AI asked for a person in a website chat chats:read
chat.closed A website chat was closed chats:read
call.missed A caller hung up before anyone answered calls:read
message.taken A live agent took a message from a caller calls:read
sms.received A customer texted one of your numbers chats:read
sms.sent A text was sent from one of your numbers chats:read

New event types may be added within the API version, so ignore types you do not handle.

Call events

call.completed carries the call's id, direction, status, numbers, times, duration_seconds and spam: true when the receptionist judged the call unwanted (no lead is created for it). Calls from numbers on your blocked callers list never reach anyone and send no event.

call.missed carries the same call object and is sent, alongside call.completed, when an inbound call ends before anyone answered it (status: "missed"). Use it to call people back quickly.

message.taken carries the same call object and is sent when a live agent who answered the call wraps it up as a message taken for you (disposition: "message_taken"). The message itself is conversation content, so it is not in the payload: fetch GET /calls/{id} for agent_notes (not for HIPAA-mode accounts).

Live chat events

Every chat.* event carries the same chat object: id, status, page_url, handed_off_at, closed_at and created_at.

  • chat.message.created adds message. sender is who wrote it (visitor, ai, agent, owner or system), role is how the widget shows it (visitor, ai, team or system) and via_api is true for replies sent with the API. To build a bot, answer visitor messages with POST /chats/{chat}/messages and skip via_api: true, which are your own.
  • chat.lead_captured adds lead, with the same fields as lead.created.
  • chat.handoff_requested adds requested_by (visitor or ai) when a person is asked for. The chat is then with_agent (a GH Live agent has it) or with_owner (waiting for your team).
  • chat.handed_off also fires when your team takes a chat over by replying.
  • chat.closed adds chat.lead_id and chat.message_count.

Text message events

sms.received (a customer texted one of your numbers) and sms.sent (a text left one of your numbers: the AI's reply, your team's, or an automatic text such as a missed-call text-back) carry the SMS conversation as chat (with channel: "sms" and the customer's number in contact_address), the message with the same fields as chat.message.created, and sms: direction, from, to, segments (how many segments the text was billed as, sent or received; null until Telnyx reports it) and automatic (true for automatic texts). Opt-out keywords such as STOP are delivered as sms.received too. SMS conversations also send the chat.* events.

HIPAA-mode accounts receive ids only, for example {"chat": {"id": 205}, "message": {"id": 4410}}.

Example payloads

These are the exact samples test deliveries send (a test delivery adds "sample": true to data).

lead.created

A lead was captured. Subscribing needs leads:read.

JSON
{
  "id": "9f0c6a1e-5b7d-4c1a-9e8f-2d3b4a5c6d7e",
  "type": "lead.created",
  "livemode": true,
  "created_at": "2026-10-02T14:03:30+00:00",
  "data": {
    "lead": {
      "id": 311,
      "call_id": 1042,
      "chat_conversation_id": null,
      "outbound_call_id": null,
      "name": "Jordan Smith",
      "phone_number": "+15555550123",
      "email": "jordan@example.com",
      "urgency": null,
      "custom_fields": [],
      "created_at": "2026-10-02T14:05:40+00:00"
    }
  }
}

call.completed

An inbound call ended. Subscribing needs calls:read.

JSON
{
  "id": "9f0c6a1e-5b7d-4c1a-9e8f-2d3b4a5c6d7e",
  "type": "call.completed",
  "livemode": true,
  "created_at": "2026-10-02T14:03:30+00:00",
  "data": {
    "call": {
      "id": 1042,
      "direction": "inbound",
      "status": "completed",
      "from_number": "+15555550123",
      "to_number": "+15555550199",
      "started_at": "2026-10-02T14:00:00+00:00",
      "ended_at": "2026-10-02T14:03:25+00:00",
      "duration_seconds": 205,
      "spam": false
    }
  }
}

booking.created

An appointment was booked. Subscribing needs bookings:read.

JSON
{
  "id": "9f0c6a1e-5b7d-4c1a-9e8f-2d3b4a5c6d7e",
  "type": "booking.created",
  "livemode": true,
  "created_at": "2026-10-02T14:03:30+00:00",
  "data": {
    "booking": {
      "id": 88,
      "call_id": 1042,
      "outbound_call_id": null,
      "provider": "google_calendar",
      "starts_at": "2026-10-05T15:30:00+00:00",
      "duration_minutes": 30,
      "name": "Jordan Smith",
      "phone_number": "+15555550123"
    }
  }
}

chat.handed_off

A website chat was handed to a person. Subscribing needs chats:read.

JSON
{
  "id": "9f0c6a1e-5b7d-4c1a-9e8f-2d3b4a5c6d7e",
  "type": "chat.handed_off",
  "livemode": true,
  "created_at": "2026-10-02T14:03:30+00:00",
  "data": {
    "chat": {
      "id": 205,
      "status": "with_owner",
      "page_url": "https://www.example.com/contact",
      "handed_off_at": "2026-10-02T14:06:00+00:00",
      "closed_at": null,
      "created_at": "2026-10-02T14:03:11+00:00"
    }
  }
}

outbound_call.completed

An outbound call ended. Subscribing needs outbound:read.

JSON
{
  "id": "9f0c6a1e-5b7d-4c1a-9e8f-2d3b4a5c6d7e",
  "type": "outbound_call.completed",
  "livemode": true,
  "created_at": "2026-10-02T14:03:30+00:00",
  "data": {
    "outbound_call": {
      "id": 57,
      "campaign_id": null,
      "source": "api",
      "purpose": "informational",
      "status": "completed",
      "contact_name": "Jordan Smith",
      "phone_number": "+15555550123",
      "blocked_reason": null,
      "answered_at": "2026-10-02T14:06:02+00:00",
      "answered_by": "human",
      "ended_at": "2026-10-02T14:08:40+00:00",
      "duration_seconds": 158
    }
  }
}

chat.started

A visitor started a website chat. Subscribing needs chats:read.

JSON
{
  "id": "9f0c6a1e-5b7d-4c1a-9e8f-2d3b4a5c6d7e",
  "type": "chat.started",
  "livemode": true,
  "created_at": "2026-10-02T14:03:30+00:00",
  "data": {
    "chat": {
      "id": 205,
      "status": "ai",
      "page_url": "https://www.example.com/contact",
      "handed_off_at": null,
      "closed_at": null,
      "created_at": "2026-10-02T14:03:11+00:00"
    }
  }
}

chat.message.created

A website chat got a new message. Subscribing needs chats:read.

JSON
{
  "id": "9f0c6a1e-5b7d-4c1a-9e8f-2d3b4a5c6d7e",
  "type": "chat.message.created",
  "livemode": true,
  "created_at": "2026-10-02T14:03:30+00:00",
  "data": {
    "chat": {
      "id": 205,
      "status": "ai",
      "page_url": "https://www.example.com/contact",
      "handed_off_at": null,
      "closed_at": null,
      "created_at": "2026-10-02T14:03:11+00:00"
    },
    "message": {
      "id": 4410,
      "sender": "visitor",
      "role": "visitor",
      "author": "Visitor",
      "body": "Hi, do you have any openings this week?",
      "via_api": false,
      "created_at": "2026-10-02T14:03:30+00:00"
    }
  }
}

chat.lead_captured

A website chat captured a lead. Subscribing needs chats:read and leads:read.

JSON
{
  "id": "9f0c6a1e-5b7d-4c1a-9e8f-2d3b4a5c6d7e",
  "type": "chat.lead_captured",
  "livemode": true,
  "created_at": "2026-10-02T14:03:30+00:00",
  "data": {
    "chat": {
      "id": 205,
      "status": "ai",
      "page_url": "https://www.example.com/contact",
      "handed_off_at": null,
      "closed_at": null,
      "created_at": "2026-10-02T14:03:11+00:00"
    },
    "lead": {
      "id": 311,
      "call_id": null,
      "chat_conversation_id": 205,
      "outbound_call_id": null,
      "name": "Jordan Smith",
      "phone_number": "+15555550123",
      "email": "jordan@example.com",
      "urgency": null,
      "custom_fields": [],
      "created_at": "2026-10-02T14:05:40+00:00"
    }
  }
}

chat.handoff_requested

The visitor or the AI asked for a person in a website chat. Subscribing needs chats:read.

JSON
{
  "id": "9f0c6a1e-5b7d-4c1a-9e8f-2d3b4a5c6d7e",
  "type": "chat.handoff_requested",
  "livemode": true,
  "created_at": "2026-10-02T14:03:30+00:00",
  "data": {
    "chat": {
      "id": 205,
      "status": "with_owner",
      "page_url": "https://www.example.com/contact",
      "handed_off_at": "2026-10-02T14:06:00+00:00",
      "closed_at": null,
      "created_at": "2026-10-02T14:03:11+00:00"
    },
    "requested_by": "visitor"
  }
}

chat.closed

A website chat was closed. Subscribing needs chats:read.

JSON
{
  "id": "9f0c6a1e-5b7d-4c1a-9e8f-2d3b4a5c6d7e",
  "type": "chat.closed",
  "livemode": true,
  "created_at": "2026-10-02T14:03:30+00:00",
  "data": {
    "chat": {
      "id": 205,
      "status": "closed",
      "page_url": "https://www.example.com/contact",
      "handed_off_at": "2026-10-02T14:06:00+00:00",
      "closed_at": "2026-10-02T14:20:12+00:00",
      "created_at": "2026-10-02T14:03:11+00:00",
      "lead_id": 311,
      "message_count": 14
    }
  }
}

call.missed

A caller hung up before anyone answered. Subscribing needs calls:read.

JSON
{
  "id": "9f0c6a1e-5b7d-4c1a-9e8f-2d3b4a5c6d7e",
  "type": "call.missed",
  "livemode": true,
  "created_at": "2026-10-02T14:03:30+00:00",
  "data": {
    "call": {
      "id": 1043,
      "direction": "inbound",
      "status": "missed",
      "from_number": "+15555550123",
      "to_number": "+15555550199",
      "started_at": "2026-10-02T14:10:00+00:00",
      "ended_at": "2026-10-02T14:10:18+00:00",
      "duration_seconds": 18,
      "spam": false
    }
  }
}

message.taken

A live agent took a message from a caller. Subscribing needs calls:read.

JSON
{
  "id": "9f0c6a1e-5b7d-4c1a-9e8f-2d3b4a5c6d7e",
  "type": "message.taken",
  "livemode": true,
  "created_at": "2026-10-02T14:03:30+00:00",
  "data": {
    "call": {
      "id": 1044,
      "direction": "inbound",
      "status": "completed",
      "from_number": "+15555550123",
      "to_number": "+15555550199",
      "started_at": "2026-10-02T14:20:00+00:00",
      "ended_at": "2026-10-02T14:23:05+00:00",
      "duration_seconds": 185,
      "spam": false
    }
  }
}

sms.received

A customer texted one of your numbers. Subscribing needs chats:read.

JSON
{
  "id": "9f0c6a1e-5b7d-4c1a-9e8f-2d3b4a5c6d7e",
  "type": "sms.received",
  "livemode": true,
  "created_at": "2026-10-02T14:03:30+00:00",
  "data": {
    "chat": {
      "id": 205,
      "status": "ai",
      "page_url": null,
      "handed_off_at": null,
      "closed_at": null,
      "created_at": "2026-10-02T14:03:11+00:00",
      "channel": "sms",
      "contact_address": "+15555550123"
    },
    "message": {
      "id": 4520,
      "sender": "visitor",
      "role": "visitor",
      "author": "Visitor",
      "body": "Hi, can someone come look at my water heater tomorrow?",
      "via_api": false,
      "created_at": "2026-10-02T15:10:02+00:00"
    },
    "sms": {
      "direction": "inbound",
      "from": "+15555550123",
      "to": "+15555550199",
      "segments": 1,
      "automatic": false
    }
  }
}

sms.sent

A text was sent from one of your numbers. Subscribing needs chats:read.

JSON
{
  "id": "9f0c6a1e-5b7d-4c1a-9e8f-2d3b4a5c6d7e",
  "type": "sms.sent",
  "livemode": true,
  "created_at": "2026-10-02T14:03:30+00:00",
  "data": {
    "chat": {
      "id": 205,
      "status": "ai",
      "page_url": null,
      "handed_off_at": null,
      "closed_at": null,
      "created_at": "2026-10-02T14:03:11+00:00",
      "channel": "sms",
      "contact_address": "+15555550123"
    },
    "message": {
      "id": 4521,
      "sender": "ai",
      "role": "ai",
      "author": "Virtual assistant",
      "body": "Yes! We have 9 AM or 1 PM tomorrow. Which works for you?",
      "via_api": false,
      "created_at": "2026-10-02T15:10:06+00:00"
    },
    "sms": {
      "direction": "outbound",
      "from": "+15555550199",
      "to": "+15555550123",
      "segments": 1,
      "automatic": false
    }
  }
}