> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vocobase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Plivo Setup

> Configure Plivo for outbound calling with the Vocobase API

# Plivo Setup

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

<Note>
  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"`.
</Note>

## Prerequisites

* A [Plivo account](https://www.plivo.com/) 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`)

<Tip>
  If `"plivo"` is not yet listed in your partner config's `allowed_telephony_providers`, contact your Vocobase account manager to enable it.
</Tip>

## Step 1: Get your Plivo credentials

<Steps>
  <Step title="Log in to the Plivo Console">
    Go to [console.plivo.com](https://console.plivo.com) and sign in.
  </Step>

  <Step title="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

    <Warning>
      Your Auth Token grants full access to your Plivo account. Treat it like a password.
    </Warning>
  </Step>

  <Step title="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>
</Steps>

## Step 2: Configure Plivo in Vocobase

Send the credentials through the Partner API.

<Note>
  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`.
</Note>

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

A successful response confirms credentials were stored:

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

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

## Step 3: Confirm the partner sees Plivo as configured

Fetch your partner configuration — the response should now include Plivo in `allowed_telephony_providers`:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.vocobase.com/api/v2/config \
    -H "Authorization: Bearer rg_live_abc123def456ghi789jkl012"
  ```
</CodeGroup>

```json theme={null}
{
  "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`.

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://api.vocobase.com/api/v2/calls/start",
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        agent_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        to_number: "+919876543210",
        provider: "plivo",
        connection_id: "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20"
      })
    }
  );
  const result = await response.json();
  console.log(result);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.vocobase.com/api/v2/calls/start",
      headers={
          "Authorization": "Bearer rg_live_abc123def456ghi789jkl012",
          "Content-Type": "application/json"
      },
      json={
          "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "to_number": "+919876543210",
          "provider": "plivo",
          "connection_id": "9b7f1c44-c87f-4f0c-9124-3c802a9c1a20"
      }
  )
  print(response.json())
  ```
</CodeGroup>

```json theme={null}
{
  "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.

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

```bash theme={null}
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

<CardGroup cols={2}>
  <Card title="Telephony Connections" icon="settings" href="/telephony/connections">
    Create and manage multiple named connections.
  </Card>

  <Card title="Twilio Setup" icon="phone" href="/telephony/twilio-setup">
    Configure Twilio as an additional telephony provider.
  </Card>

  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Create an agent and make your first call.
  </Card>
</CardGroup>