For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
WebsiteStatusSupportDashboard
DocumentationAPI ReferenceMCPSDKsCLI (new)What's New?
DocumentationAPI ReferenceMCPSDKsCLI (new)What's New?
  • Get started
    • Introduction
    • Phone calls
    • Web calls
    • Vapi Guides
    • Composer
    • CLI quickstart
  • Assistants
    • Quickstart
    • Tools
    • Custom keywords
    • Custom voices
    • Custom transcriber
    • Custom TTS
  • Observability
    • Boards
  • Squads
    • Quickstart
    • Overview
    • Handoff tool
    • Passing data between assistants
  • Best practices
    • Prompting guide
    • Debugging voice agents
    • Enterprise environments (DEV/UAT/PROD)
    • IVR navigation
  • Phone numbers
    • Free Vapi number
    • Inbound SMS
    • Phone Number Hooks
  • Calls
    • Call end reasons
    • Troubleshoot call errors
  • Outbound Campaigns
    • Quickstart
    • Overview
  • Chat
    • Quickstart
    • Streaming
    • Non-streaming
    • OpenAI compatibility
    • Session management
    • Variable substitution
    • SMS chat
    • Web widget
    • Webhooks
  • Workflows
    • Quickstart
    • Overview
LogoLogo
WebsiteStatusSupportDashboard
On this page
  • Overview
  • Usage
  • Example: Say Message on Call Ringing
  • Example: Transfer on Call Ringing
Phone numbers

Phone Number Hooks

Was this page helpful?
Edit this page
Previous

Phone Calling

Learn how to create and configure phone numbers with Vapi
Next
Built with

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