Phone numbers

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:

Phone number hooks are configured through the API and are not currently available in the Dashboard.

  • 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