Phone Number Hooks

Phone Number Hooks

Phone number hooks allow you to configure actions that will be performed when specific events occur during a call. Currently, hooks support the call.ringing event (which is triggered when a call is ringing).

Usage

Hooks are defined in the hooks array of a phone number. Each hook consists of:

  • on: The event that triggers the hook (supports call.ringing)
  • do: The actions to perform when the hook triggers (supports transfer and say)

Example: Say Message on Call Ringing

This example shows how to play a message when a call is ringing:

$curl -X PATCH "https://api.vapi.ai/phone-number/<id>" \
> -H "Authorization: Bearer <auth>" \
> -H "Content-Type: application/json" \
> -d '{
> "hooks": [{
> "on": "call.ringing",
> "do": [{
> "type": "say",
> "exact": "inbound calling is disabled."
> }]
> }]
>}'

Example: Transfer on Call Ringing

This example shows how to transfer a call when it starts ringing:

$curl -X PATCH "https://api.vapi.ai/phone-number/<id>" \
> -H "Authorization: Bearer <auth>" \
> -H "Content-Type: application/json" \
> -d '{
> "hooks": [{
> "on": "call.ringing",
> "do": [{
> "type": "transfer",
> "destination": {
> "type": "number",
> "number": "+1234567890",
> "callerId": "+1987654321"
> }
> }]
> }]
>}'

You can also transfer to a SIP destination:

$curl -X PATCH "https://api.vapi.ai/phone-number/<id>" \
> -H "Authorization: Bearer <auth>" \
> -H "Content-Type: application/json" \
> -d '{
> "hooks": [{
> "on": "call.ringing",
> "do": [{
> "type": "transfer",
> "destination": {
> "type": "sip",
> "sipUri": "sip:user@domain.com"
> }
> }]
> }]
>}'

Common use cases for phone number hooks include:

  • Disabling inbound calling by playing a message or transferring