Plivo Setup

This guide walks you through connecting your Plivo account to Vocobase for outbound calling.

Configure Plivo with the V2 API (PUT /api/v2/config/telephony/plivo) for the default connection. To create multiple named Plivo connections, use POST /api/v2/telephony/connections. Once Plivo is configured, start calls programmatically using POST /calls/start with "provider": "plivo".

Prerequisites

A Plivo account with a verified Auth ID and Auth Token
At least one Plivo phone number with Voice enabled
An approved Vocobase account with "plivo" present in allowed_telephony_providers (check GET /config)

If "plivo" is not yet listed in your account config’s allowed_telephony_providers, contact your Vocobase account manager to enable it.

Get your Plivo credentials

Go to console.plivo.com and sign in.

Copy your Auth ID and Auth Token

From the Overview page, copy your Auth ID and Auth Token.

Auth ID — 20-character string starting with MA (production) or SA (subaccounts)
Auth Token — 40-character alphanumeric string

Your Auth Token grants full access to your Plivo account. Treat it like a password.

Identify the phone number you will call from

Navigate to Phone Numbers > Your Numbers. Copy the number you plan to use as the caller ID.The number must be in E.164 format (e.g., +14155551234) and must have Voice capabilities enabled.

Configure Plivo in Vocobase

Send the credentials through the V2 API.

This endpoint updates your default Plivo connection. To create multiple named Plivo connections, use POST /api/v2/telephony/connections and store the returned connection_id.

curl -X PUT https://api.vocobase.com/api/v2/config/telephony/plivo \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "auth_id": "MAxxxxxxxxxxxxxxxxxx",
    "auth_token": "your_plivo_auth_token",
    "from_number": "+14155551234"
  }'

const response = await fetch(
  "https://api.vocobase.com/api/v2/config/telephony/plivo",
  {
    method: "PUT",
    headers: {
      "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      auth_id: "MAxxxxxxxxxxxxxxxxxx",
      auth_token: "your_plivo_auth_token",
      from_number: "+14155551234"
    })
  }
);
const result = await response.json();
console.log(result);

import requests

response = requests.put(
    "https://api.vocobase.com/api/v2/config/telephony/plivo",
    headers={
        "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
        "Content-Type": "application/json"
    },
    json={
        "auth_id": "MAxxxxxxxxxxxxxxxxxx",
        "auth_token": "your_plivo_auth_token",
        "from_number": "+14155551234"
    }
)
print(response.json())

A successful response confirms credentials were stored:

{
  "success": true,
  "data": {
    "auth_id": "MAxx****xxxx",
    "from_number": "+14155551234",
    "message": "Plivo credentials updated successfully."
  }
}

Your Auth Token is encrypted at rest and never returned in API responses. The Auth ID is masked.

To rotate credentials later, send the same request again with the new values. Every field is required on each call — the endpoint replaces the stored credential set rather than patching it.

Confirm it is configured

GET /api/v2/config reports Plivo under allowed_telephony_providers and shows telephony.plivo.configured: true once your credentials are saved. See Check provider access.

Make a test call

Start an outbound call with "provider": "plivo".

curl -X POST https://api.vocobase.com/api/v2/calls/start \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "to_number": "+919876543210",
    "provider": "plivo"
  }'

Vocobase manages the carrier connection and media path for Plivo. Accounts only need to configure credentials and pass "provider": "plivo" when starting calls. If your account has more than one active Plivo connection, also pass connection_id — omitting it returns CONNECTION_AMBIGUOUS. See Bring Your Own Phone for the full request and response shape.

Optional: voicemail detection

For Plivo outbound calls, supported accounts can enable carrier-side voicemail detection per agent. Set voicemail_detection_enabled to control detection for that agent. If voicemail_message is present and Plivo detects voicemail, Vocobase redirects the call to speak that message and then hang up. If no message is configured, the detected voicemail call is ended without playback.

Carrier-side voicemail detection must be enabled for your Plivo connection by Vocobase before these agent settings affect live calls.

curl -X PUT https://api.vocobase.com/api/v2/agent/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{
    "voicemail_detection_enabled": true,
    "voicemail_message": "Hi, this is Priya from Acme Corp. I will call you back soon."
  }'

Troubleshooting

”Plivo not configured” or 403 on `/calls/start`

Confirm "plivo" is in allowed_telephony_providers from GET /config. If it is not, contact your Vocobase account manager.

401 from Plivo during verification

Auth ID or Auth Token is wrong. Re-copy from the Plivo Console.
If you recently rotated the Auth Token in Plivo, send PUT /config/telephony/plivo again with the new token.

Calls ring but drop immediately

The Plivo number you are calling from must have Voice Application enabled, not only Messaging.
Confirm the destination number is reachable from Plivo. Some Plivo accounts have geographic restrictions that require explicit enablement.
Check the Plivo console Logs > Call Logs — Plivo logs the exact reason a call was dropped (e.g., “Invalid from number”, “No route to destination”).

Caller ID shows “Unknown”

Ensure the number in your Plivo account matches an imported number on your Vocobase connection. If you added numbers after initial setup, sync them through the V2 phone-numbers API.

Next steps

Telephony Connections

Create and manage multiple named connections.

Twilio Setup

Configure Twilio as an additional telephony provider.

Quick Start

Create an agent and make your first call.

Getting Started

Building Agents

Making Calls

Receiving Calls

After the Call

Telephony Providers

Advanced

API Reference

Endpoints

Plivo Setup

Plivo Setup

Prerequisites

Get your Plivo credentials

Configure Plivo in Vocobase

Confirm it is configured

Make a test call

Optional: voicemail detection

Troubleshooting

”Plivo not configured” or 403 on `/calls/start`

401 from Plivo during verification

Calls ring but drop immediately

Caller ID shows “Unknown”

Next steps

Telephony Connections

Twilio Setup

Quick Start

​Plivo Setup

​Prerequisites

​Get your Plivo credentials

​Configure Plivo in Vocobase

​Confirm it is configured

​Make a test call

​Optional: voicemail detection

​Troubleshooting

​”Plivo not configured” or 403 on /calls/start

​401 from Plivo during verification

​Calls ring but drop immediately

​Caller ID shows “Unknown”

​Next steps

Telephony Connections

Twilio Setup

Quick Start

Plivo Setup

Prerequisites

Get your Plivo credentials

Configure Plivo in Vocobase

Confirm it is configured

Make a test call

Optional: voicemail detection

Troubleshooting

”Plivo not configured” or 403 on `/calls/start`

401 from Plivo during verification

Calls ring but drop immediately

Caller ID shows “Unknown”

Next steps