Phone numbersSIP integration

SIP introduction

Make SIP calls to your Vapi assistant

Overview

This guide shows you how to set up and test SIP calls to your Vapi assistant using any SIP client or softphone. You’ll create an assistant, assign it a SIP phone number, and make a call using a SIP URI. You can also pass template variables via SIP headers.

A Vapi SIP phone number supports inbound calls only because it has a sipUri but no public switched telephone network (PSTN) phone number for outbound calls. Outbound attempts fail with call.start.error-get-transport and the message Vapi Numbers Can't Dial Outbound Yet.

To place outbound calls, import a phone number from a supported provider or connect your own SIP trunk. Use a SIP trunk for international destinations.

Choose your Vapi region

Use the API base URL, private key, and SIP host from the same Vapi region. Do not create a SIP phone number in one region with a SIP URI from another region.

RegionDashboardAPI base URLSIP host
United Statesdashboard.vapi.aihttps://api.vapi.aisip.vapi.ai
European Uniondashboard.eu.vapi.aihttps://api.eu.vapi.aisip.eu.vapi.ai

Vapi offers an EU region with EU dashboard, API, and SIP endpoints. For more information, see EU region and data residency.

For existing EU organizations, create the SIP phone number against the EU API with an EU dashboard private key:

curl -X POST https://api.eu.vapi.ai/phone-number \
  -H "Authorization: Bearer $VAPI_EU_PRIVATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "vapi",
    "name": "EU SIP Assistant",
    "sipUri": "sip:your_unique_user_name@sip.eu.vapi.ai",
    "assistantId": "your_eu_assistant_id"
  }'

If your SIP provider or firewall requires IP allowlisting, use the signalling IPs for your region from the SIP networking and firewall configuration reference.

1

Create an assistant

Create an assistant with the POST /assistant endpoint. This is the same as creating an assistant for any other transport.

{
  "name": "My SIP Assistant",
  "firstMessage": "Hello {{first_name}}, you've reached me over SIP."
}
2

Create a SIP phone number

Create a SIP phone number with the POST /phone-number endpoint for your region.

{
  "provider": "vapi",
  "sipUri": "sip:your_unique_user_name@sip.vapi.ai",
  "assistantId": "your_assistant_id"
}

sipUri must be in the format sip:username@<sip-host>, where <sip-host> matches your Vapi region. You can choose any username you like.

3

Start a SIP call

Use any SIP softphone (e.g., Zoiper, Linphone) to dial your SIP URI (e.g., sip:your_unique_user_name@sip.vapi.ai).

The assistant will answer your call. No authentication or SIP registration is required.

4

Send SIP headers to fill template variables

To fill template variables, send custom SIP headers with your call.

For example, to fill the first_name variable, send a SIP header:

x-first_name: John

Header names are case-insensitive (e.g., X-First_Name, x-first_name, and X-FIRST_NAME all work).

5

Use a custom assistant for each call

You can use a custom assistant for SIP calls just like for phone calls.

Set the assistantId to null and the serverUrl to your server, which will respond to the assistant-request event.

PATCH /phone-number/:id

{
  "assistantId": null,
  "serverUrl": "https://your_server_url"
}

Now, every time you make a call to this phone number, your server will receive an assistant-request event.