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

# Phone Calling

> Create and configure phone numbers in Vapi. Use a free US number to receive inbound calls, or import a number from a provider to place outbound and international calls.

## Overview

> **Warning**
>
> Free Vapi phone numbers use US area codes, and only inbound calls are supported. To make outbound calls, import a number from [Twilio](/phone-numbers/import-twilio), [Telnyx](/telnyx), or [DIDWW](/phone-numbers/didww). You get one free Vapi number, which you can request without adding a payment method, and your Success Package may include more. See [Pricing and Success Packages](/billing/pricing-and-success-packages#whats-included).

You can create and configure phone numbers with Vapi to place and receive calls. Vapi provides free US phone numbers for inbound calls. For outbound, international, or custom use, import your own numbers from a provider.

If you're configuring a phone number with an AI coding assistant, the [create-phone-number skill](/agent-skills#create-phone-number) helps you plan, provision, import, and route it.

## Setting up a phone number

You can set up a phone number to place and receive calls in two ways:

* **Create a free US phone number:**
  * Use the Vapi dashboard or the [`/phone-numbers`](/api-reference/phone-numbers/create) endpoint.
  * With free numbers, only inbound calls are supported. See [Free Vapi numbers](/free-telephony).

* **Import your own number (for international or custom use):**
  * Use the dashboard or the [Phone Numbers API](/api-reference/phone-numbers/create).
  * Follow the guide for your provider: [Twilio](/phone-numbers/import-twilio), [Telnyx](/telnyx), [DIDWW](/phone-numbers/didww), or a [SIP trunk](/advanced/sip/sip-trunk).

## Outbound calls

You can place an outbound call from one of your phone numbers using the [`/call`](/api-reference/calls/create-phone-call) endpoint.

* If the system message will be different with every call, specify a temporary assistant in the `assistant` field.
* To reuse an assistant, specify its ID in the `assistantId` field.
* [Read more about outbound calls](/calls/outbound-calling)
* Outbound calls aren't supported on free Vapi numbers. Use an imported number.

## Inbound calls

You can provide an `assistantId` to a phone number, and it will use that assistant for inbound calls.

* To specify the assistant based on the caller's phone number, leave the `assistantId` blank. Vapi will attempt to retrieve the assistant from your server using your [Server URL](/server-url/events#retrieving-assistants).

## Video tutorial: Importing numbers from Twilio for international calls

> Learn how to create and configure phone numbers with Vapi

## Docs

- [Outbound Calling](https://docs.vapi.ai/calls/outbound-calling.md): Send outbound calls from Vapi programmatically, placing single or batch calls and scheduling them for reminders, surveys, and automated call campaigns.
- [WebSocket Transport](https://docs.vapi.ai/calls/websocket-transport.md): Stream audio directly via WebSockets for real-time, bidirectional communication
- [Live Call Control](https://docs.vapi.ai/calls/call-features.md): Control live Vapi calls in real time with Call Control to inject conversation elements and Call Listen to stream call audio over a WebSocket connection.
- [Customer Join Timeout](https://docs.vapi.ai/calls/customer-join-timeout.md): Set maximum time for users to join web calls before automatic termination
- [Voicemail Detection](https://docs.vapi.ai/calls/voicemail-detection.md): Detect voicemail on outbound Vapi calls to handle it faster and more flexibly, keeping your voice agents efficient when a call reaches an answering machine.
- [Transfer Call tool](https://docs.vapi.ai/tools/transfer-call.md): Create a transfer call tool in the Vapi Dashboard or API, add it to an assistant, configure destinations, and troubleshoot invocation and routing failures.
- [Configure assistant-based warm transfer](https://docs.vapi.ai/calls/assistant-based-warm-transfer.md): Configure an assistant-based warm transfer in the Vapi Dashboard or API, including operator prompts, fallback behavior, summaries, custom audio, and testing.
- [Dynamic call transfers](https://docs.vapi.ai/calls/call-dynamic-transfers.md): Learn how Vapi's dynamic call transfers work and explore implementation patterns for intelligent call routing.
- [Transfer calls using API Request and Transfer Call tools](https://docs.vapi.ai/calls/transfer-calls-with-api-lookup.md): Use API Request and Transfer Call tools to look up a branch by ZIP code, get caller consent, transfer to a configured phone number, and test lookup failures.
- [Call Handling with Vapi and Twilio](https://docs.vapi.ai/calls/call-handling-with-vapi-and-twilio.md): Keep a caller on hold while dialing a specialist using Vapi and Twilio, with a fallback action when the specialist misses the call or it reaches voicemail.
- [Debug call forwarding drops](https://docs.vapi.ai/phone-calling/in-call-control/transfer-calls/debug-forwarding-drops.md): Troubleshoot Vapi calls that drop immediately after a transfer, finding why forwarding disconnects both parties and how to resolve the underlying cause.
- [Call queue management with Twilio](https://docs.vapi.ai/calls/call-queue-management.md): Build a call queue system using Twilio to handle large volumes of calls while respecting Vapi concurrency limits, ensuring no calls are dropped.
- [Understanding Call Concurrency](https://docs.vapi.ai/calls/call-concurrency.md): Learn how concurrency slots work, how to stay within the default limit, and how to raise capacity for larger campaigns.
- [Call ended reasons](https://docs.vapi.ai/calls/call-ended-reason.md): Understand Vapi endedReason codes that explain why a call ended, where to find them in call logs and the Call object, and how to diagnose each one.
- [Troubleshoot call errors](https://docs.vapi.ai/calls/troubleshoot-call-errors.md): Diagnose failed Vapi calls by what the caller experienced, with errors organized by symptom so you can jump to the right fix for each call failure.
- [Call analysis](https://docs.vapi.ai/assistants/call-analysis.md): Automatically summarize and evaluate every Vapi call after it ends, using an LLM to generate summaries, extract structured data, and score calls for quality.
- [Call recording, logging and transcribing](https://docs.vapi.ai/assistants/call-recording.md): Learn how to configure artifact plans to record calls, generate transcripts, and store logs for analysis
- [Retrieve call artifacts](https://docs.vapi.ai/assistants/retrieve-call-artifacts.md): How to download call recordings and logs from Vapi's private storage using your Private API Key and short-lived, authenticated redirect URLs.