Phone Number Hooks

Overview

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