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

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

Outbound Call Flow

Create a call via
```
POST /call
```
with
```
phoneNumberId
```
and
```
customer.number
```
Vapi dials the customer from your phone number
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

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 for full setup instructions across all supported agents.

create-phone-number

NPX Install

Tags

SKILL.md Content

Vapi Phone Number Setup

Quick Start — Buy a Vapi Number

Import from Twilio

Import from Vonage

Import from Telnyx

Assign an Assistant

Phone Number Hooks

Managing Phone Numbers

Inbound Call Flow

Outbound Call Flow

Free Number Limitations

References

Additional Resources