Skip to main content

​
Plivo Setup

This guide walks you through connecting your Plivo account to Vocobase for outbound calling.
Configure Plivo with the Partner 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 partner account with "plivo" present in allowed_telephony_providers (check GET /config)
If "plivo" is not yet listed in your partner config’s allowed_telephony_providers, contact your Vocobase account manager to enable it.

​
Step 1: Get your Plivo credentials

1

Log in to the Plivo Console

Go to console.plivo.com and sign in.
2

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

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.

​
Step 2: Configure Plivo in Vocobase

Send the credentials through the Partner 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"
  }'
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.

​
Step 3: Confirm the partner sees Plivo as configured

Fetch your partner configuration — the response should now include Plivo in allowed_telephony_providers: 
curl -X GET https://api.vocobase.com/api/v2/config \
  -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"

{
  "success": true,
  "data": {
    "name": "acme-corp",
    "allowed_telephony_providers": ["twilio", "plivo"],
    "telephony": {
      "twilio": { "configured": true, "account_sid": "conf****ured", "from_number": "+14155551111" },
      "mcube": { "configured": false, "exe_number": null },
      "exotel": { "configured": false, "account_sid": null, "subdomain": null, "caller_id": null, "applet_id": null },
      "plivo": { "configured": true, "auth_id": "conf****ured", "from_number": "+14155551234" }
    },
    "...": "..."
  }
}
telephony.plivo.configured: true confirms the credentials landed and a default from-number is set. Presence in allowed_telephony_providers is what gates your ability to start a Plivo call — if Plivo isn’t in that list, contact your Vocobase account manager to enable it.

​
Step 4: Make a test call

Start an outbound call with "provider": "plivo". If your partner account has multiple active Plivo connections, include connection_id. 
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",
    "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20"
  }'

{
  "success": true,
  "data": {
    "call_id": "c1234567-abcd-1234-abcd-123456789012",
    "session_id": "s1234567-abcd-1234-abcd-123456789012",
    "status": "pending",
    "provider": "plivo",
    "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20",
    "from_number": "+14155551234",
    "to_number": "+919876543210",
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
Vocobase manages the carrier connection and media path for Plivo. Partners only need to configure credentials and pass "provider": "plivo" when starting calls. Passing only "provider": "plivo" remains valid while there is exactly one active Plivo connection.

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

​
CONNECTION_AMBIGUOUS error

  • Your account has multiple active Plivo connections. Call GET /api/v2/telephony/connections?provider=plivo and pass the desired connection_id in POST /api/v2/calls/start.

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

​
Updating credentials

Rotate the Auth Token in Plivo, then update Vocobase by re-sending PUT /api/v2/config/telephony/plivo with the new token.

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