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.createdaddsmessage.senderis who wrote it (visitor,ai,agent,ownerorsystem),roleis how the widget shows it (visitor,ai,teamorsystem) andvia_apiistruefor replies sent with the API. To build a bot, answer visitor messages withPOST /chats/{chat}/messagesand skipvia_api: true, which are your own.chat.lead_capturedaddslead, with the same fields aslead.created.chat.handoff_requestedaddsrequested_by(visitororai) when a person is asked for. The chat is thenwith_agent(a GH Live agent has it) orwith_owner(waiting for your team).chat.handed_offalso fires when your team takes a chat over by replying.chat.closedaddschat.lead_idandchat.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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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
}
}
}