Skip to content

Commit b73c7af

Browse files
fern-api[bot]fern-api[bot]
committed
Merge remote-tracking branch 'origin/main' into fern/update-api-specs
2 parents 1707f55 + da35944 commit b73c7af

File tree

3 files changed

+192
-0
lines changed

3 files changed

+192
-0
lines changed

‎fern/advanced/sip/sip-trunk.mdx‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
title: SIP Trunking Guide for Vapi
3+
subtitle: How to integrate your SIP provider with Vapi
4+
slug: advanced/sip/sip-trunk
5+
---
6+
7+
SIP trunking replaces traditional phone lines with a virtual connection over the internet, allowing your business to make and receive calls via a broadband connection. It connects your internal PBX or VoIP system to a SIP provider, which then routes calls to the Public Switched Telephone Network (PSTN). This setup simplifies your communications infrastructure and often reduces costs.
8+
9+
## 1. Vapi SIP Trunking Options
10+
11+
Vapi supports multiple SIP trunk configurations, including:
12+
13+
- **Telnyx**: Uses SIP gateway domain (e.g., sip.telnyx.com) with IP-based authentication. May require a tech prefix for outbound calls.
14+
- **Zadarma**: Uses SIP credentials (username/password) with its SIP server (e.g., sip.zadarma.com).
15+
- **Custom "BYO" SIP Trunk**: Allows integration with any SIP provider. You simply provide the SIP gateway address and the necessary authentication details.
16+
17+
## 2. Setup Process Overview
18+
19+
To set up a SIP trunk in Vapi, follow these steps:
20+
21+
### Obtain Provider Details
22+
23+
Gather the SIP server address, authentication credentials (username/password or IP-based), and at least one phone number (DID) from your provider.
24+
25+
### Create a SIP Trunk Credential in Vapi
26+
27+
Use the Vapi API to create a new credential (type: byo-sip-trunk) with your provider's details. This informs Vapi how to connect to your SIP network.
28+
29+
**Example (using Zadarma):**
30+
31+
```bash
32+
curl -X POST "https://api.vapi.ai/credential" \
33+
-H "Content-Type: application/json" \
34+
-H "Authorization: Bearer YOUR_VAPI_PRIVATE_KEY" \
35+
-d '{
36+
"provider": "byo-sip-trunk",
37+
"name": "Zadarma Trunk",
38+
"gateways": [{
39+
"ip": "sip.zadarma.com"
40+
}],
41+
"outboundLeadingPlusEnabled": true,
42+
"outboundAuthenticationPlan": {
43+
"authUsername": "YOUR_SIP_NUMBER",
44+
"authPassword": "YOUR_SIP_PASSWORD"
45+
}
46+
}'
47+
```
48+
49+
Save the returned Credential ID for later use.
50+
51+
### Associate a Phone Number with the SIP Trunk
52+
53+
Link your external phone number (DID) to the SIP trunk credential in Vapi by creating a Phone Number resource.
54+
55+
**Example:**
56+
57+
```bash
58+
curl -X POST "https://api.vapi.ai/phone-number" \
59+
-H "Content-Type: application/json" \
60+
-H "Authorization: Bearer YOUR_VAPI_PRIVATE_KEY" \
61+
-d '{
62+
"provider": "byo-phone-number",
63+
"name": "Zadarma Number",
64+
"number": "15551234567",
65+
"numberE164CheckEnabled": false,
66+
"credentialId": "YOUR_CREDENTIAL_ID"
67+
}'
68+
```
69+
70+
Note the returned Phone Number ID for use in test calls.
71+
72+
### Test Your SIP Trunk
73+
74+
#### Outbound Call Test
75+
76+
Initiate a call through the Vapi dashboard or API to ensure outbound calls are properly routed.
77+
78+
**API Example:**
79+
80+
```json
81+
POST https://api.vapi.ai/call/phone
82+
{
83+
"assistantId": "YOUR_ASSISTANT_ID",
84+
"customer": {
85+
"number": "15557654321",
86+
"numberE164CheckEnabled": false
87+
},
88+
"phoneNumberId": "YOUR_PHONE_NUMBER_ID"
89+
}
90+
```
91+
92+
#### Inbound Call Test
93+
94+
If inbound routing is configured, call your phone number from an external line. Ensure your provider forwards calls to the correct SIP URI (e.g., `{phoneNumber}@sip.vapi.ai` for Zadarma).

‎fern/advanced/sip/sip-zadarma.mdx‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
title: Zadarma SIP Integration
3+
subtitle: How to integrate SIP Zadarma to Vapi
4+
slug: advanced/sip/zadarma
5+
---
6+
7+
8+
Integrate your Zadarma SIP trunk with Vapi.ai to enable your AI voice assistants to handle calls efficiently. Follow the steps below to set up this integration:
9+
10+
## 1. Retrieve Your Vapi.ai Private Key
11+
12+
- Log in to your Vapi.ai account.
13+
- Navigate to **Organization Settings**.
14+
- In the **API Keys** section, copy your **Private Key**.
15+
16+
## 2. Add Your Zadarma SIP Credentials to Vapi.ai
17+
18+
You'll need to send a `curl` request to Vapi.ai's API to add your SIP credentials:
19+
20+
- **Private Key**: Your Vapi.ai private key.
21+
- **Trunk Name**: A name for your SIP trunk (e.g., "Zadarma Trunk").
22+
- **Server Address**: The server address provided by Zadarma (e.g., "sip.zadarma.com").
23+
- **SIP Number**: Your Zadarma SIP number.
24+
- **SIP Password**: The password for your Zadarma SIP number.
25+
26+
Here's the `curl` command to execute:
27+
28+
```bash
29+
curl -L 'https://api.vapi.ai/credential' \\
30+
-H 'Content-Type: application/json' \\
31+
-H 'Authorization: Bearer YOUR_PRIVATE_KEY' \\
32+
-d '{
33+
"provider": "byo-sip-trunk",
34+
"name": "Zadarma Trunk",
35+
"gateways": [
36+
{ "ip": "sip.zadarma.com" }
37+
],
38+
"outboundLeadingPlusEnabled": true,
39+
"outboundAuthenticationPlan": {
40+
"authUsername": "YOUR_SIP_NUMBER",
41+
"authPassword": "YOUR_SIP_PASSWORD"
42+
}
43+
}'
44+
```
45+
Replace `YOUR_PRIVATE_KEY`, `YOUR_SIP_NUMBER`, and `YOUR_SIP_PASSWORD` with your actual credentials.
46+
47+
If successful, the response will include an `id` for the created credential, which you'll use in the next step.
48+
49+
## 3. Add Your Virtual Number to Vapi.ai
50+
51+
Next, associate your virtual number with the SIP trunk in Vapi.ai:
52+
53+
- **Private Key**: Your Vapi.ai private key.
54+
- **Number Name**: A name for your virtual number (e.g., "Zadarma Number").
55+
- **Virtual Number**: Your Zadarma virtual number in international format (e.g., "15551111111").
56+
- **Credential ID**: The `id` from the previous step.
57+
58+
Use the following `curl` command:
59+
60+
```bash
61+
curl -L 'https://api.vapi.ai/phone-number' \\
62+
-H 'Content-Type: application/json' \\
63+
-H 'Authorization: Bearer YOUR_PRIVATE_KEY' \\
64+
-d '{
65+
"provider": "byo-phone-number",
66+
"name": "Zadarma Number",
67+
"number": "YOUR_VIRTUAL_NUMBER",
68+
"numberE164CheckEnabled": false,
69+
"credentialId": "YOUR_CREDENTIAL_ID"
70+
}'
71+
```
72+
73+
Replace `YOUR_PRIVATE_KEY`, `YOUR_VIRTUAL_NUMBER`, and `YOUR_CREDENTIAL_ID` with your actual details.
74+
75+
## 4. Assign Your Voice Assistant to Handle Calls
76+
77+
- In your Vapi.ai dashboard, go to the **Build** section and select **Phone Numbers**.
78+
- Click on your **Zadarma Number**.
79+
- In the **Inbound Settings** section, assign your voice assistant to handle incoming calls.
80+
- In the **Outbound Form** section, assign your voice assistant to handle outgoing calls.
81+
82+
## 5. Configure Incoming Call Reception in Zadarma
83+
84+
To forward incoming calls from your Zadarma virtual number to Vapi.ai:
85+
86+
- Log in to your Zadarma account.
87+
- Navigate to **Settings** → **Virtual phone numbers**.
88+
- Click the ⚙ (gear) icon next to your number.
89+
- Open the **External server** tab.
90+
- Enable **External server (SIP URI)**.
91+
- Enter the address: `[email protected]` (replace `YOUR_VIRTUAL_NUMBER` with your number in international format).
92+
- Click **Save**.
93+
94+
By following these steps, your Zadarma SIP trunk will be integrated with Vapi.ai, allowing your AI voice assistants to manage calls effectively.

‎fern/docs.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -237,8 +237,12 @@ navigation:
237237
- section: SIP Telephony
238238
path: advanced/sip/sip.mdx
239239
contents:
240+
- page: SIP Trunking
241+
path: advanced/sip/sip-trunk.mdx
240242
- page: Telnyx Integration
241243
path: advanced/sip/sip-telnyx.mdx
244+
- page: Zadarma Integration
245+
path: advanced/sip/sip-zadarma.mdx
242246
- section: Advanced Concepts
243247
contents:
244248
- page: Multilingual Support

0 commit comments

Comments
 (0)