Connect Any Orchestration Platform

The Plivo side of a voice agent integration is the same regardless of which orchestration platform you use. If your platform supports SIP trunking, this guide connects it to the phone network through Plivo, even if Plivo doesn’t have a dedicated guide for it. Each step includes both the API and the Console option.

Prerequisites

Requirement	Description
Plivo Account	Sign up with SIP trunking enabled
Phone Number	Purchase a voice-enabled number India: Requires KYC verification. See Rent India Numbers.
Orchestration platform	An account with any voice agent platform that supports SIP trunking

If you’re using the API, you also need your Plivo Auth ID and Auth Token, available on the Plivo Console home page. Export them 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>"

From your platform’s documentation, you need three facts:

Its SIP endpoint: the host Plivo should send inbound calls to (often sip.<platform>.com), and which transport it expects (UDP, TCP, or TLS)
Its outbound authentication method: SIP digest credentials (username and password), or a published list of static IP addresses
Where to enter Plivo’s details: the screen where you register a phone number and configure a SIP trunk

India traffic: calls to or from India require your platform to terminate SIP and media in India. See Calling in India before you start.

Part 1: Receive Incoming Calls

Route calls from your Plivo phone number to your platform.

Step 1: Create an Inbound Trunk in Plivo

API
Console

First, create an origination URI that points to your platform’s SIP endpoint, including the transport parameter it expects:

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": "My platform SIP endpoint",
        "uri": "sip.example-platform.com;transport=tcp",
    },
)
print(response.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 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: 'My platform SIP endpoint',
    uri: 'sip.example-platform.com;transport=tcp',
  }),
});
console.log(await response.json());

Copy the uri_uuid from the response. Next, create an inbound trunk using the origination URI as the primary URI:

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 platform inbound trunk",
        "trunk_direction": "inbound",
        "primary_uri_uuid": "<uri_uuid>",
    },
)
print(response.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 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 platform inbound trunk',
    trunk_direction: 'inbound',
    primary_uri_uuid: '<uri_uuid>',
  }),
});
console.log(await response.json());

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

Go to SIP Trunking → Inbound Trunks
Click Create New Inbound Trunk and enter a name (e.g., MyPlatform-Inbound)
Click Add New URI and enter your platform’s SIP endpoint, including the transport parameter it expects:

Field	Value
Name	`MyPlatform-Primary`
SIP URI	`sip.example-platform.com;transport=tcp`

Click Create Trunk

The transport parameter must match what your platform expects. A mismatch is the most common reason an inbound integration fails silently. For TLS, use port 5061: sip.example-platform.com:5061;transport=tls.

Step 2: Connect Your Phone Number

API
Console

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:

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

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());

A successful response returns HTTP 202 with the message changed.

Go to Your Numbers
Click on your phone number
Set Application Type to Zentrunk
Set Trunk to your inbound trunk
Click Update Number

Step 3: Configure Your Platform

On your platform, register the Plivo number and attach an agent to it. This step varies by platform; look for “SIP trunk”, “BYO carrier”, or “phone numbers” in its documentation. Call your Plivo number. Your agent should answer.

Part 2: Make Outgoing Calls

Enable your platform to place calls through Plivo.

Step 1: Create Authentication

Choose the method your platform supports: SIP digest credentials when your platform authenticates with a username and password or its IPs are dynamic, or an IP access control list when it publishes static IP addresses for its SIP traffic.

API
Console

To create a credential, use a username of 5 to 20 alphanumeric characters and a password of 5 to 20 characters with at least one of the special characters ~!@#$%^&*()_+:

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": "My platform outbound credential",
        "username": "<username>",
        "password": "<password>",
    },
)
print(response.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 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: 'My platform outbound credential',
    username: '<username>',
    password: '<password>',
  }),
});
console.log(await response.json());

Copy the credential_uuid from the response.Alternatively, create an IP access control list with your platform’s published IP addresses:

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/IPAccessControlList/",
    auth=(auth_id, auth_token),
    json={
        "name": "My platform IPs",
        "ip_addresses": ["203.0.113.10", "203.0.113.11"],
    },
)
print(response.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 response = await fetch(`https://api.plivo.com/v1/Account/${authId}/Zentrunk/IPAccessControlList/`, {
  method: 'POST',
  headers: {
    'Authorization': authHeader,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'My platform IPs',
    ip_addresses: ['203.0.113.10', '203.0.113.11'],
  }),
});
console.log(await response.json());

Copy the ipacl_uuid from the response.

Credentials:

Go to SIP Trunking → Outbound Trunks
Click Add New Credentials List and create credentials:
- Username: myplatform_trunk (or your preferred username)
- Password: Generate a strong password

IP access control list:

Go to SIP Trunking → Outbound Trunks → IP Access Control List
Click Create New IP Access Control List and enter a name (e.g., MyPlatform-IPs)
Add the IP addresses from your platform’s documentation
Click Create

Step 2: Create an Outbound Trunk in Plivo

API
Console

Create an outbound trunk using the credential or IP ACL from Step 1. Pass credential_uuid, ipacl_uuid, or both. Set secure to true if your platform supports TLS and SRTP (recommended):

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 platform outbound trunk",
        "trunk_direction": "outbound",
        "credential_uuid": "<credential_uuid>",
        "secure": True,
    },
)
print(response.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 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 platform outbound trunk',
    trunk_direction: 'outbound',
    credential_uuid: '<credential_uuid>',
    secure: true,
  }),
});
console.log(await response.json());

Copy the trunk_id from the response, then retrieve the trunk to get your Termination SIP Domain from the trunk_domain field (e.g., 21784177241578.zt.plivo.com):

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

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());

Go to SIP Trunking → Outbound Trunks
Click Create New Outbound Trunk and enter a name (e.g., MyPlatform-Outbound)
Select the credentials list or IP ACL from Step 1
Enable Secure Trunking if your platform supports TLS and SRTP (recommended)
Click Create Trunk
Copy your Termination SIP Domain (e.g., XXXXXXXXXXXX.zt.plivo.com)

Step 3: Configure Your Platform

In your platform’s outbound trunk settings, enter:

Setting	Value
SIP domain / termination URI	Your Termination SIP Domain from Step 2
Username and password	The credentials from Step 1 (if using credentials)
Caller ID	A Plivo number you rent, or a verified caller ID

Caller ID must be a Plivo number. Outbound calls that present a non-Plivo number fail with hangup code 4190 (unknown_caller_id). See Hangup codes.

If your platform sends SIP OPTIONS pings for health checks, point them at the outbound trunk URI only, at most one ping every 10 to 15 seconds. Higher frequency may trigger blocking. See Technical Specifications.

Troubleshooting

Issue	Solution
Inbound call doesn’t connect	Verify the trunk URI matches your platform’s SIP endpoint exactly, including the `transport` parameter. Confirm the number’s Application Type is `Zentrunk` and points at the right trunk.
Outbound authentication fails	Credentials must match exactly on both sides. For IP ACLs, confirm the platform’s current IP list; platforms occasionally add addresses.
Outbound calls fail immediately	Check the caller ID is a Plivo number (hangup 4190). Check debug logs for the hangup code.
One-way or no audio on India calls	See Calling in India; hangup 4590 indicates a media anchoring violation.

Debug logs: for inbound issues, check Plivo logs first; for outbound issues, check your platform’s logs first. For error codes, see Hangup codes.

API Reference - Create trunks, credentials, URIs, and IP ACLs programmatically
Technical Specifications - Codecs, ports, IP ranges, and supported SIP features
Your First Agent Call - Quickstart with per-platform SIP URIs

​Prerequisites

​Part 1: Receive Incoming Calls

​Step 1: Create an Inbound Trunk in Plivo

​Step 2: Connect Your Phone Number

​Step 3: Configure Your Platform

​Part 2: Make Outgoing Calls

​Step 1: Create Authentication

​Step 2: Create an Outbound Trunk in Plivo

​Step 3: Configure Your Platform

​Troubleshooting

​Related

Prerequisites

Part 1: Receive Incoming Calls

Step 1: Create an Inbound Trunk in Plivo

Step 2: Connect Your Phone Number

Step 3: Configure Your Platform

Part 2: Make Outgoing Calls

Step 1: Create Authentication

Step 2: Create an Outbound Trunk in Plivo

Step 3: Configure Your Platform

Troubleshooting

Related