Retell AI Integration

Connect Plivo SIP trunking to Retell AI to enable your voice agents to make and receive phone calls through Plivo’s global voice network. This guide uses Retell’s elastic SIP trunking approach recommended for connecting custom telephony providers. You can configure Plivo using the Console or the API; each step in this guide includes both options. This guide follows a single linear flow: set up both trunks in Plivo, then import your number into Retell once.

Prerequisites

Requirement	Description
Plivo Account	Sign up with SIP trunking enabled
Phone Number	Purchase a voice-enabled number
Retell Account	Create account with at least one agent configured

If you’re using the API, you also need:

Your Plivo Auth ID and Auth Token, available on the Plivo Console home page. The Plivo API uses HTTP Basic authentication.
Your Retell API key, available on the API Keys page of the Retell dashboard. The Retell API uses Bearer authentication.

Export your credentials as environment variables to use with the code samples in this guide:

export PLIVO_AUTH_ID="<your_auth_id>"
export PLIVO_AUTH_TOKEN="<your_auth_token>"
export RETELL_API_KEY="<your_retell_api_key>"

Indian phone numbers: TRAI regulations require voice AI platforms to terminate SIP traffic on servers located in India. Confirm with Retell support that your deployment meets this requirement before using Indian phone numbers.

How the integration works

Direction	Call path	What you configure
Inbound	Caller → Plivo number → Plivo inbound trunk → `sip.retellai.com` → Retell agent	Inbound trunk in Plivo pointing to Retell’s SIP server
Outbound	Retell agent → Plivo outbound trunk → PSTN → Callee	Outbound trunk in Plivo; its termination domain and credentials go into Retell’s number import

Set up both trunks for a fully working number. The outbound trunk is always required — Retell won’t import a number without its termination URI, even for inbound-only use. The inbound trunk routes calls to your agent; skip the inbound trunk and phone number steps only if your agent exclusively makes outbound calls.

Set up the integration

Create an outbound trunk in Plivo

Set up an outbound trunk with username and password authentication in Plivo. Retell uses the trunk’s Termination SIP Domain and these credentials to place outbound calls.

Console
API

Sign in to the Plivo Console.
Navigate to SIP Trunking → Outbound Trunks.
Select Create Trunk and provide a descriptive name for your trunk.
In the Trunk Authentication section → Credential, select Create new credential.
Add a credential name, and a username and strong password for outbound call authentication, then select Create credential.
- Username: 5 to 20 characters, alphanumeric only.
- Password: 5 to 20 characters, using only alphanumeric characters and the special characters ~!@#$%^&*()_+, with at least one special character.
- Use the same username and password when you import your number into Retell.
For Authentication, select the credential you created in the previous step.
Optional: enable Secure Trunking to encrypt SIP signaling over TLS.
Select Create Trunk to complete your outbound trunk configuration.

Copy the Termination SIP Domain (for example, 21784177241578.zt.plivo.com). You need it when you import your number into Retell.

First, create a credential with a username and strong password for outbound call authentication:

Username: 5 to 20 characters, alphanumeric only.
Password: 5 to 20 characters, using only alphanumeric characters and the special characters ~!@#$%^&*()_+, with at least one special character.
Use the same username and password when you import your number into Retell.

curl "https://api.plivo.com/v1/Account/$PLIVO_AUTH_ID/Zentrunk/Credential/" \
-u "$PLIVO_AUTH_ID:$PLIVO_AUTH_TOKEN" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "name": "Retell outbound credential",
  "username": "<username>",
  "password": "<password>"
}'

const authId = process.env.PLIVO_AUTH_ID;
const authToken = process.env.PLIVO_AUTH_TOKEN;
const authHeader = 'Basic ' + Buffer.from(`${authId}:${authToken}`).toString('base64');

const response = await fetch(`https://api.plivo.com/v1/Account/${authId}/Zentrunk/Credential/`, {
  method: 'POST',
  headers: {
    'Authorization': authHeader,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Retell outbound credential',
    username: '<username>',
    password: '<password>',
  }),
});
console.log(await response.json());

import os
import requests

auth_id = os.environ["PLIVO_AUTH_ID"]
auth_token = os.environ["PLIVO_AUTH_TOKEN"]

response = requests.post(
    f"https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Credential/",
    auth=(auth_id, auth_token),
    json={
        "name": "Retell outbound credential",
        "username": "<username>",
        "password": "<password>",
    },
)
print(response.json())

Copy the credential_uuid from the response for the next step:

{
  "api_id": "<api_id>",
  "message": "Credential created successfully",
  "credential_uuid": "<credential_uuid>"
}

Next, create an outbound trunk using the credential. To encrypt SIP signaling over TLS, add "secure": true to the request:

curl "https://api.plivo.com/v1/Account/$PLIVO_AUTH_ID/Zentrunk/Trunk/" \
-u "$PLIVO_AUTH_ID:$PLIVO_AUTH_TOKEN" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "name": "My Retell outbound trunk",
  "trunk_direction": "outbound",
  "credential_uuid": "<credential_uuid>"
}'

const authId = process.env.PLIVO_AUTH_ID;
const authToken = process.env.PLIVO_AUTH_TOKEN;
const authHeader = 'Basic ' + Buffer.from(`${authId}:${authToken}`).toString('base64');

const response = await fetch(`https://api.plivo.com/v1/Account/${authId}/Zentrunk/Trunk/`, {
  method: 'POST',
  headers: {
    'Authorization': authHeader,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'My Retell outbound trunk',
    trunk_direction: 'outbound',
    credential_uuid: '<credential_uuid>',
  }),
});
console.log(await response.json());

import os
import requests

auth_id = os.environ["PLIVO_AUTH_ID"]
auth_token = os.environ["PLIVO_AUTH_TOKEN"]

response = requests.post(
    f"https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Trunk/",
    auth=(auth_id, auth_token),
    json={
        "name": "My Retell outbound trunk",
        "trunk_direction": "outbound",
        "credential_uuid": "<credential_uuid>",
    },
)
print(response.json())

Copy the trunk_id from the response:

{
  "api_id": "<api_id>",
  "message": "Trunk created successfully.",
  "trunk_id": "<trunk_id>"
}

Finally, retrieve the trunk to get your Termination SIP Domain. It’s returned in the trunk_domain field. For example, 21784177241578.zt.plivo.com:

curl "https://api.plivo.com/v1/Account/$PLIVO_AUTH_ID/Zentrunk/Trunk/<trunk_id>/" \
-u "$PLIVO_AUTH_ID:$PLIVO_AUTH_TOKEN" \
-H 'Accept: application/json'

const authId = process.env.PLIVO_AUTH_ID;
const authToken = process.env.PLIVO_AUTH_TOKEN;
const authHeader = 'Basic ' + Buffer.from(`${authId}:${authToken}`).toString('base64');
const trunkId = '<trunk_id>';

const response = await fetch(`https://api.plivo.com/v1/Account/${authId}/Zentrunk/Trunk/${trunkId}/`, {
  headers: { 'Authorization': authHeader },
});
console.log(await response.json());

import os
import requests

auth_id = os.environ["PLIVO_AUTH_ID"]
auth_token = os.environ["PLIVO_AUTH_TOKEN"]
trunk_id = "<trunk_id>"

response = requests.get(
    f"https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Trunk/{trunk_id}/",
    auth=(auth_id, auth_token),
)
print(response.json())

Copy the Termination SIP Domain (trunk_domain). You need it when you import your number into Retell.

Create an inbound trunk in Plivo

Create an inbound trunk that routes calls from your Plivo phone number to Retell’s SIP server.

Console
API

Navigate to SIP Trunking → Inbound Trunks.
Select Create Trunk and provide a descriptive name for your trunk.
For Primary URI, select Add New URI and enter Retell’s SIP server: sip.retellai.com;transport=tcp.
For Link Numbers, select your phone number from the dropdown menu. Or connect your phone number in the next step.
Select Create Trunk.

First, create an origination URI that points to Retell’s SIP server:

curl "https://api.plivo.com/v1/Account/$PLIVO_AUTH_ID/Zentrunk/URI/" \
-u "$PLIVO_AUTH_ID:$PLIVO_AUTH_TOKEN" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "name": "Retell SIP server",
  "uri": "sip.retellai.com;transport=tcp"
}'

const authId = process.env.PLIVO_AUTH_ID;
const authToken = process.env.PLIVO_AUTH_TOKEN;
const authHeader = 'Basic ' + Buffer.from(`${authId}:${authToken}`).toString('base64');

const response = await fetch(`https://api.plivo.com/v1/Account/${authId}/Zentrunk/URI/`, {
  method: 'POST',
  headers: {
    'Authorization': authHeader,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Retell SIP server',
    uri: 'sip.retellai.com;transport=tcp',
  }),
});
console.log(await response.json());

import os
import requests

auth_id = os.environ["PLIVO_AUTH_ID"]
auth_token = os.environ["PLIVO_AUTH_TOKEN"]

response = requests.post(
    f"https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/URI/",
    auth=(auth_id, auth_token),
    json={
        "name": "Retell SIP server",
        "uri": "sip.retellai.com;transport=tcp",
    },
)
print(response.json())

Copy the uri_uuid from the response for the next step:

{
  "api_id": "<api_id>",
  "message": "Origination URI created successfully",
  "uri_uuid": "<uri_uuid>"
}

Next, create an inbound trunk using the origination URI as the primary URI:

curl "https://api.plivo.com/v1/Account/$PLIVO_AUTH_ID/Zentrunk/Trunk/" \
-u "$PLIVO_AUTH_ID:$PLIVO_AUTH_TOKEN" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "name": "My Retell inbound trunk",
  "trunk_direction": "inbound",
  "primary_uri_uuid": "<uri_uuid>"
}'

const authId = process.env.PLIVO_AUTH_ID;
const authToken = process.env.PLIVO_AUTH_TOKEN;
const authHeader = 'Basic ' + Buffer.from(`${authId}:${authToken}`).toString('base64');

const response = await fetch(`https://api.plivo.com/v1/Account/${authId}/Zentrunk/Trunk/`, {
  method: 'POST',
  headers: {
    'Authorization': authHeader,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'My Retell inbound trunk',
    trunk_direction: 'inbound',
    primary_uri_uuid: '<uri_uuid>',
  }),
});
console.log(await response.json());

import os
import requests

auth_id = os.environ["PLIVO_AUTH_ID"]
auth_token = os.environ["PLIVO_AUTH_TOKEN"]

response = requests.post(
    f"https://api.plivo.com/v1/Account/{auth_id}/Zentrunk/Trunk/",
    auth=(auth_id, auth_token),
    json={
        "name": "My Retell inbound trunk",
        "trunk_direction": "inbound",
        "primary_uri_uuid": "<uri_uuid>",
    },
)
print(response.json())

Copy the trunk_id from the response. You use it to connect your phone number in the next step:

{
  "api_id": "<api_id>",
  "message": "Trunk created successfully.",
  "trunk_id": "<trunk_id>"
}

Connect your phone number

Connect your Plivo phone number to the inbound trunk. You can skip this step if you connected your phone number when you created the inbound trunk.

Console
API

Navigate to Phone Numbers → Purchased Numbers.
Select the phone number to connect to the trunk.
For Application Type, select SIP Trunk.
For Trunk, select the inbound trunk you created in the previous step.
Select Save changes.

Assign the inbound trunk to your phone number using the update a number endpoint. Set the app_id field to the trunk ID of your inbound trunk. Use your phone number in E.164 format without the leading +. For example, 15105550100:

curl "https://api.plivo.com/v1/Account/$PLIVO_AUTH_ID/Number/15105550100/" \
-u "$PLIVO_AUTH_ID:$PLIVO_AUTH_TOKEN" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "app_id": "<trunk_id>"
}'

const authId = process.env.PLIVO_AUTH_ID;
const authToken = process.env.PLIVO_AUTH_TOKEN;
const authHeader = 'Basic ' + Buffer.from(`${authId}:${authToken}`).toString('base64');
const phoneNumber = '15105550100';

const response = await fetch(`https://api.plivo.com/v1/Account/${authId}/Number/${phoneNumber}/`, {
  method: 'POST',
  headers: {
    'Authorization': authHeader,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    app_id: '<trunk_id>',
  }),
});
console.log(await response.json());

import os
import requests

auth_id = os.environ["PLIVO_AUTH_ID"]
auth_token = os.environ["PLIVO_AUTH_TOKEN"]
phone_number = "15105550100"

response = requests.post(
    f"https://api.plivo.com/v1/Account/{auth_id}/Number/{phone_number}/",
    auth=(auth_id, auth_token),
    json={
        "app_id": "<trunk_id>",
    },
)
print(response.json())

A successful response returns HTTP 202:

{
  "api_id": "<api_id>",
  "message": "changed"
}

Import your number into Retell

Import your Plivo phone number into Retell using the Termination SIP Domain and the credential username and password from the outbound trunk you created earlier.

Dashboard
API

Sign in to the Retell dashboard.
Navigate to Phone Numbers, select the option to add a number, and choose Connect to your number via SIP trunking.
Configure the import with the following values:

Field	Value
Phone Number	Your Plivo number in E.164 format. For example, `+15105550100`.
Termination URI	Your Plivo Termination SIP Domain. For example, `21784177241578.zt.plivo.com`. Don’t enter Retell’s SIP server URI here.
SIP Trunk User Name	The credential username from your Plivo outbound trunk.
SIP Trunk Password	The credential password from your Plivo outbound trunk.
Nickname (optional)	A descriptive label. For example, `Plivo support line`.
Outbound Transport	Keep the default, TCP. Select TLS if Secure Trunking is enabled on your Plivo outbound trunk.

Select Save.
After the number is imported, bind an inbound agent and an outbound agent to it. A number can only receive or make calls after an agent is bound in that direction.

To learn more, see the Retell custom telephony guide.

Import the number with Retell’s Import Phone Number API. You can bind inbound and outbound agents in the same request.Set transport to TLS if Secure Trunking is enabled on your Plivo outbound trunk; otherwise, use TCP:

curl "https://api.retellai.com/import-phone-number" \
-H "Authorization: Bearer $RETELL_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
  "phone_number": "+15105550100",
  "termination_uri": "<trunk_id>.zt.plivo.com",
  "sip_trunk_auth_username": "<username>",
  "sip_trunk_auth_password": "<password>",
  "transport": "TCP",
  "nickname": "Plivo support line",
  "inbound_agents": [{ "agent_id": "<agent_id>", "weight": 1 }],
  "outbound_agents": [{ "agent_id": "<agent_id>", "weight": 1 }]
}'

const response = await fetch('https://api.retellai.com/import-phone-number', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.RETELL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    phone_number: '+15105550100',
    termination_uri: '<trunk_id>.zt.plivo.com',
    sip_trunk_auth_username: '<username>',
    sip_trunk_auth_password: '<password>',
    transport: 'TCP',
    nickname: 'Plivo support line',
    inbound_agents: [{ agent_id: '<agent_id>', weight: 1 }],
    outbound_agents: [{ agent_id: '<agent_id>', weight: 1 }],
  }),
});
console.log(await response.json());

import os
import requests

response = requests.post(
    "https://api.retellai.com/import-phone-number",
    headers={"Authorization": f"Bearer {os.environ['RETELL_API_KEY']}"},
    json={
        "phone_number": "+15105550100",
        "termination_uri": "<trunk_id>.zt.plivo.com",
        "sip_trunk_auth_username": "<username>",
        "sip_trunk_auth_password": "<password>",
        "transport": "TCP",
        "nickname": "Plivo support line",
        "inbound_agents": [{"agent_id": "<agent_id>", "weight": 1}],
        "outbound_agents": [{"agent_id": "<agent_id>", "weight": 1}],
    },
)
print(response.json())

A successful response returns HTTP 201 with the imported number details:

{
  "phone_number": "+15105550100",
  "phone_number_pretty": "+1 (510) 555-0100",
  "phone_number_type": "custom",
  "nickname": "Plivo support line",
  "inbound_agents": [{ "agent_id": "<agent_id>", "weight": 1 }],
  "sip_outbound_trunk_config": {
    "termination_uri": "<trunk_id>.zt.plivo.com",
    "auth_username": "<username>",
    "transport": "TCP"
  },
  "last_modification_timestamp": 1703413636133
}

Changing trunk configuration: Retell doesn’t support editing an imported number’s SIP trunk settings. To change the termination URI or credentials, delete the number in Retell and import it again.

Test your integration

Inbound: Call your Plivo phone number. The Retell agent bound to the number should answer the call.Outbound: Place a call from the Retell dashboard, or use Retell’s Create Phone Call API. Set from_number to your imported Plivo number:

curl "https://api.retellai.com/v2/create-phone-call" \
-H "Authorization: Bearer $RETELL_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
  "from_number": "+15105550100",
  "to_number": "+12135550123"
}'

const response = await fetch('https://api.retellai.com/v2/create-phone-call', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.RETELL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from_number: '+15105550100',
    to_number: '+12135550123',
  }),
});
console.log(await response.json());

import os
import requests

response = requests.post(
    "https://api.retellai.com/v2/create-phone-call",
    headers={"Authorization": f"Bearer {os.environ['RETELL_API_KEY']}"},
    json={
        "from_number": "+15105550100",
        "to_number": "+12135550123",
    },
)
print(response.json())

Troubleshooting

Trunk configuration errors typically surface only when a call is placed, so test both directions after setup. If a call fails to connect, check the following common issues:

Issue	Solution
Inbound call doesn’t connect	Verify the inbound trunk’s primary URI is `sip.retellai.com;transport=tcp` and your phone number is connected to the inbound trunk. Confirm an inbound agent is bound to the number in Retell.
Outbound call fails	Verify the termination URI in Retell matches your Plivo Termination SIP Domain exactly, with no spaces or `sip:` prefix. Confirm the credential username and password match.
Authentication errors	Verify credentials match exactly in both Plivo and Retell. Use the credential username, not the credential name.
Calls drop or have no audio	If Secure Trunking is enabled on your Plivo outbound trunk, set Outbound Transport to TLS in Retell.

Debug logs:

Inbound issues: First check the Plivo logs, then check call history in the Retell dashboard.
Outbound issues: First check call history in the Retell dashboard, then check the Plivo logs.

For error codes, see Plivo hangup codes.

SIP Trunking API overview

Plivo SIP Trunking API reference.

SIP Trunking for voice agents

Concepts and architecture for building voice agents with Plivo SIP trunking.

Retell custom telephony guide

Retell’s guide to connecting custom telephony providers.

Retell API reference

Retell’s Import Phone Number API documentation.

​Prerequisites

​How the integration works

​Set up the integration

Create an outbound trunk in Plivo

Create an inbound trunk in Plivo

Connect your phone number

Import your number into Retell

Test your integration

​Troubleshooting

​Related

SIP Trunking API overview

SIP Trunking for voice agents

Retell custom telephony guide

Retell API reference

Prerequisites

How the integration works

Set up the integration

Troubleshooting

Related