> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.vapi.ai/llms.txt.
> For full documentation content, see https://docs.vapi.ai/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.vapi.ai/_mcp/server.

# 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:

```bash
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:

```bash
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:

```bash
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