create-phone-number

# Vapi Phone Number Setup

Import phone numbers from Twilio, Vonage, or Telnyx, or use Vapi's built-in numbers to connect voice assistants to real phone calls.

> **Setup:** Ensure `VAPI_API_KEY` is set. See the `setup-api-key` skill if needed.

## Quick Start — Buy a Vapi Number

Vapi provides free phone numbers for testing with daily call limits.

```bash
curl -X POST https://api.vapi.ai/phone-number \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "vapi",
    "assistantId": "your-assistant-id",
    "name": "Main Support Line"
  }'
```

## Import from Twilio

```bash
curl -X POST https://api.vapi.ai/phone-number \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "twilio",
    "number": "+11234567890",
    "twilioAccountSid": "your-twilio-account-sid",
    "twilioAuthToken": "your-twilio-auth-token",
    "assistantId": "your-assistant-id",
    "name": "Twilio Support Line"
  }'
```

## Import from Vonage

```bash
curl -X POST https://api.vapi.ai/phone-number \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "vonage",
    "number": "+11234567890",
    "credentialId": "your-vonage-credential-id",
    "assistantId": "your-assistant-id",
    "name": "Vonage Support Line"
  }'
```

## Import from Telnyx

```bash
curl -X POST https://api.vapi.ai/phone-number \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "telnyx",
    "number": "+11234567890",
    "credentialId": "your-telnyx-credential-id",
    "assistantId": "your-assistant-id",
    "name": "Telnyx Support Line"
  }'
```

## Assign an Assistant

Every phone number can be linked to an assistant or squad for inbound calls:

```bash
curl -X PATCH https://api.vapi.ai/phone-number/{id} \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistantId": "your-assistant-id"
  }'
```

Or assign a squad:
```bash
curl -X PATCH https://api.vapi.ai/phone-number/{id} \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "squadId": "your-squad-id"
  }'
```

## Phone Number Hooks

Configure automated actions when calls come in:

```json
{
  "hooks": [
    {
      "on": "call.ringing",
      "do": [
        {
          "type": "say",
          "exact": "Please hold while we connect you."
        }
      ]
    }
  ]
}
```

## Managing Phone Numbers

```bash
# List all phone numbers
curl https://api.vapi.ai/phone-number \
  -H "Authorization: Bearer $VAPI_API_KEY"

# Get a phone number
curl https://api.vapi.ai/phone-number/{id} \
  -H "Authorization: Bearer $VAPI_API_KEY"

# Update a phone number
curl -X PATCH https://api.vapi.ai/phone-number/{id} \
  -H "Authorization: Bearer $VAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Name"}'

# Delete a phone number
curl -X DELETE https://api.vapi.ai/phone-number/{id} \
  -H "Authorization: Bearer $VAPI_API_KEY"
```

## Inbound Call Flow

1. Caller dials your Vapi phone number
2. Vapi routes the call to the assigned assistant or squad
3. The assistant speaks its `firstMessage`
4. The conversation proceeds with the configured model, voice, and tools

## Outbound Call Flow

1. Create a call via `POST /call` with `phoneNumberId` and `customer.number`
2. Vapi dials the customer from your phone number
3. When answered, the assistant begins the conversation

## Free Number Limitations

- Cannot make international calls
- Daily call limits apply
- For production use, import your own Twilio/Vonage/Telnyx numbers

## References

- [Vapi Phone Numbers Docs](https://docs.vapi.ai/phone-numbers/import-twilio)
- [Free Telephony](https://docs.vapi.ai/free-telephony)
- [Phone Number Hooks](https://docs.vapi.ai/phone-numbers/phone-number-hooks)

## Additional Resources

This skills repository includes a **Vapi documentation MCP server** (`vapi-docs`) that gives your AI agent access to the full Vapi knowledge base. Use the `searchDocs` tool to look up anything beyond what this skill covers — advanced configuration, troubleshooting, SDK details, and more.

**Auto-configured:** If you cloned or installed these skills, the MCP server is already configured via `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), or `.vscode/mcp.json` (VS Code Copilot).

**Manual setup:** If your agent doesn't auto-detect the config, run:
```bash
claude mcp add vapi-docs -- npx -y mcp-remote https://docs.vapi.ai/_mcp/server
```

See the [README](../README.md#vapi-documentation-server-mcp) for full setup instructions across all supported agents.