SIP introduction

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.

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.

Region	Dashboard	API base URL	SIP host
United States	`dashboard.vapi.ai`	`https://api.vapi.ai`	`sip.vapi.ai`
European Union	`dashboard.eu.vapi.ai`	`https://api.eu.vapi.ai`	`sip.eu.vapi.ai`

For 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.

Create an assistant

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

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

Create a SIP phone number

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

1 {
2   "provider": "vapi",
3   "sipUri": "sip:your_unique_user_name@sip.vapi.ai",
4   "assistantId": "your_assistant_id"
5 }

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

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.

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).

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

1 {
2   "assistantId": null,
3   "serverUrl": "https://your_server_url"
4 }

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