# Phone webhooks

Events for calls, SMS registrations, RCS agents, Branded Calling identities and numbers, and watched number stock.

## Events

### Calls

Call events need inbox access. Without it, `POST /v1/webhooks/settings` returns a `403` with code `feature_not_available`.

| Event | Description |
| --- | --- |
| [`call.received`](/webhooks/phone/call-received) | An inbound call reached your number, or an outbound WhatsApp call was placed. |
| [`call.ended`](/webhooks/phone/call-ended) | A call ended; carries duration, end reason and costs. |
| [`call.failed`](/webhooks/phone/call-failed) | A call failed with a hard error. |
| [`call.permission_request`](/webhooks/phone/call-permission-request) | A WhatsApp user answered your call-permission request. |

### SMS and RCS

`sms.registration.*` events follow a [US SMS registration](/platforms/sms/setup) (10DLC or toll-free) through carrier review. `rcs.agent.status_updated` follows an [RCS agent](/platforms/rcs/connect).

| Event | Description |
| --- | --- |
| [`sms.registration.status_updated`](/webhooks/phone/sms-registration-status-updated) | An SMS registration changed status. |
| [`sms.registration.action_required`](/webhooks/phone/sms-registration-action-required) | An SMS registration is waiting on its owner. |
| [`rcs.agent.status_updated`](/webhooks/phone/rcs-agent-status-updated) | An RCS agent moved to a new status. |

### Branded calling

These events follow a [caller identity](/platforms/phone-numbers/branded-calling) and its numbers.

| Event | Description |
| --- | --- |
| [`branded_calling.identity.status_updated`](/webhooks/phone/branded-calling-identity-status-updated) | A caller identity changed status. |
| [`branded_calling.identity.action_required`](/webhooks/phone/branded-calling-identity-action-required) | A caller identity is waiting on you. |
| [`branded_calling.number.status_updated`](/webhooks/phone/branded-calling-number-status-updated) | An attached number changed vetting status. |

### Number stock

| Event | Description |
| --- | --- |
| [`phone_number.stock_available`](/webhooks/phone/phone-number-stock-available) | A watched out-of-stock country has numbers again. |

## How it behaves

<Accordions>
<Accordion title="Which events fire, in what order" id="which-events-fire-in-what-order">

Zernio ends every call with exactly one of `call.ended` or `call.failed`. `call.permission_request` reports a reply to a permission prompt, not a call.

| Call | Sequence |
| --- | --- |
| Inbound, phone or WhatsApp | `call.received` at ring time, then `call.ended` or `call.failed` |
| Outbound WhatsApp (through the API) | `call.received` with `direction: "outbound"` at origination, then `call.ended` or `call.failed` |
| Outbound phone (API or browser softphone) | `call.ended` or `call.failed` only |

</Accordion>
<Accordion title="`call.received` fires at ring time" id="callreceived-fires-at-ring-time">

It fires before anyone answers, so a call nobody picks up still emits it. See the event page.

</Accordion>
<Accordion title="Unanswered calls end with `call.ended`" id="unanswered-calls-end-with-callended">

No-answer, busy and rejected calls end with `call.ended`; branch on `endReason`. `call.failed` is reserved for hard errors before or during bridging.

</Accordion>
<Accordion title="Permission requests are independent of any call" id="permission-requests-are-independent-of-any-call">

Zernio sends `call.permission_request` when a WhatsApp user responds to a [call-permission request](/platforms/whatsapp/calling). It gates business-initiated WhatsApp calls.

</Accordion>
<Accordion title="Every SMS registration status change fires `status_updated`" id="every-sms-registration-status-change-fires-status_updated">

Zernio sends `sms.registration.status_updated` on each transition. Statuses are listed on the event page.

</Accordion>
<Accordion title="SMS `action_required` fires only when you must act" id="sms-action_required-fires-only-when-you-must-act">

Answer with [Respond to registration review](/sms/respond-to-sms-registration-review) or [Verify registration OTP](/sms/verify-sms-registration-otp). Reasons are listed on the event page.

</Accordion>
<Accordion title="The registration is the key, not an account" id="the-registration-is-the-key-not-an-account">

These events belong to no connected account.

`registration.id` is the registration id. `registration.profileId` is its profile, which [profile-scoped endpoints](/webhooks#routing-by-profile-or-account) filter on.

</Accordion>
<Accordion title="Every RCS agent status change fires once" id="every-rcs-agent-status-change-fires-once">

Zernio sends `rcs.agent.status_updated` each time an agent moves into a status. Statuses are listed on the event page.

</Accordion>
<Accordion title="Branded calling events fire on status transitions" id="branded-calling-events-fire-on-status-transitions">

Zernio polls the carrier every 15 minutes while an identity or a batch of numbers is being vetted, so a carrier decision reaches you within that window.

</Accordion>
<Accordion title="Branded calling `action_required` needs you" id="branded-calling-action_required-needs-you">

Every `action_required` is paired with a `status_updated`. Reasons are listed on the event page.

</Accordion>
<Accordion title="Numbers are vetted after the identity" id="numbers-are-vetted-after-the-identity">

Number events start once the identity is `verified` and you attached numbers. A batch is vetted as a unit; each number reports its own status.

</Accordion>
<Accordion title="Number stock fires once per watch" id="number-stock-fires-once-per-watch">

`phone_number.stock_available` belongs to a stock watch, not to a number. The watch is consumed on firing ([availability](/platforms/phone-numbers/availability)).

</Accordion>
</Accordions>

## Related

- [Webhooks](/webhooks): create an endpoint, retries, signatures.
- [Voice history](/platforms/voice/history): calls and recordings on demand.
- [WhatsApp calling](/platforms/whatsapp/calling): call permissions and business-initiated calls.
- [Phone numbers](/platforms/phone-numbers): provision the numbers these calls land on.
- [SMS registration](/platforms/sms/setup): register a US number for 10DLC or toll-free.
- [Get SMS registration](/sms/get-sms-registration): read `status` on demand.
- [Branded Calling](/platforms/phone-numbers/branded-calling): the whole flow, with every status.
- [WhatsApp webhooks](/webhooks/whatsapp): number activation, suspension and release.