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

# Bolna Integration

> Connect Plivo with Bolna to power multilingual voice AI agents on your own Plivo numbers

[Bolna](https://www.bolna.ai/) is a platform for building multilingual voice AI agents. Connect your Plivo account to Bolna, and Bolna agents make and receive phone calls on your Plivo numbers. Calls run on your own Plivo account and are billed to it.

***

## How it works

Call flow

Bolna

<ol>
  <li>
    Phone Call

    Plivo
    Number + Application

    Answer URL
    Call audio

    Bolna
    Voice agent
  </li>
</ol>

You connect Plivo to Bolna once with your Auth ID and Auth Token. After that, Bolna handles the call flow:

* **Outbound** — Bolna dials out through your connected Plivo account, using a Plivo number as the caller ID. No Plivo console changes are required.
* **Inbound** — you point a Plivo Application's **Answer URL** at Bolna's inbound URL and link your number to that Application. When someone calls the number, Plivo fetches Bolna's URL and connects the caller to the assigned Bolna agent.

***

## Prerequisites

| Requirement | Description |
| - | - |
| **Plivo account** | [Sign up](https://cx.plivo.com/signup) and copy the Auth ID and Auth Token from the [Plivo console](https://cx.plivo.com/home) |
| **Phone number** | A [voice-enabled Plivo number](https://cx.plivo.com/phone-numbers) in E.164 format. In India, a number requires KYC verification — see [Rent India numbers](https://plivo.com/docs/numbers/rent-india-numbers.md) |
| **Bolna account** | A [Bolna account](https://platform.bolna.ai/) with at least one agent |

***

## Connect Plivo to Bolna

Connect your Plivo account once, then set Plivo as the agent's telephony provider.

### 1. Add your Plivo credentials to Bolna

**Console**

1. In the Bolna dashboard, go to **Settings → Integrations**.
2. Filter by **Telephony** and select **Connect** on the Plivo card.
3. Enter your **Auth ID**, **Auth Token**, and a Plivo **phone number** in E.164 format.
4. Select **Connect**.

**API**

Send your Plivo credentials to Bolna, authenticated with a Bolna API key. Bolna stores them as `PLIVO_AUTH_ID`, `PLIVO_AUTH_TOKEN`, and `PLIVO_PHONE_NUMBER`.

Refer to Bolna's [Add a provider](https://www.bolna.ai/docs/api-reference/providers/add) for all parameters.

### 2. Set Plivo as the agent's provider

1. Open your agent in Bolna.
2. On the **Call** tab, set the telephony provider to **Plivo**.
3. Save the agent.

Your Plivo numbers are available as the caller ID only after the account is connected.

***

## Make outbound calls

Bolna dials out through your connected Plivo account. No Plivo console changes are required.

### 1. Place a call

Open the agent in Bolna, enter the destination number in E.164 format, and select **Call**.

To trigger calls from your own application, use Bolna's [Make a call](https://www.bolna.ai/docs/api-reference/calls/make) endpoint:

```bash theme={null}
curl -X POST "https://api.bolna.ai/call" \
-H "Authorization: Bearer $BOLNA_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
  "agent_id": "<agent_id>",
  "recipient_phone_number": "+14155550123"
}'
```

### 2. Check the call

The response returns an `execution_id`. Retrieve it with Bolna's [Get an execution](https://www.bolna.ai/docs/api-reference/executions/get_execution) endpoint for the transcript, cost, and telephony data.

A call moves through these [statuses](https://www.bolna.ai/docs/post-call/list-phone-call-status): `queued` → `ringing` → `in-progress` → `call-disconnected` → `completed`. The `completed` status can take two to three minutes to appear after the call ends.

For campaigns across many numbers, see Bolna's [Batch APIs](https://www.bolna.ai/docs/api-reference/batches/overview).

***

## Receive inbound calls

Route calls from your Plivo number to a Bolna agent by pointing a Plivo Application's Answer URL at Bolna's inbound URL.

### 1. Get the inbound URL from Bolna

1. Open your agent in Bolna and copy the **inbound URL** shown on it.
2. Assign the agent to your number under **My Numbers**.

Copy the URL in full, including its query string — the `agent_id` and `user_id` parameters identify the agent that answers. To do this programmatically, see Bolna's [Set inbound agent](https://www.bolna.ai/docs/api-reference/inbound/agent).

### 2. Create an application in Plivo

**Console**

1. In the [Plivo console](https://cx.plivo.com/), go to **Voice → Applications** and select **Add New Application**.
2. Enter a name, for example `bolna-inbound`.
3. Configure these fields, then select **Create Application**:

| Field | Value |
| - | - |
| **Answer URL** | Your Bolna inbound URL, with method **POST** |
| **Hangup URL** | The same Bolna inbound URL |

**API**

Create the Application with the Bolna inbound URL as both the Answer URL and the Hangup URL, authenticated with your Auth ID and Auth Token over Basic auth.

Refer to the [Application API](https://plivo.com/docs/account/api/application.md) for all parameters.

```bash theme={null}
curl -X POST "https://api.plivo.com/v1/Account/$PLIVO_AUTH_ID/Application/" \
-u '<auth_id>:<auth_token>' \
-H 'Content-Type: application/json' \
-d '{
  "app_name": "bolna-inbound",
  "answer_url": "<bolna_inbound_url>",
  "answer_method": "POST",
  "hangup_url": "<bolna_inbound_url>"
}'
```

### 3. Connect your phone number

1. In the [Plivo console](https://cx.plivo.com/), go to **Phone Numbers → Your Numbers** and open your number.
2. Set its **Application** to the application you created.
3. Select **Update Number**.

### 4. Test

Call your Plivo number. The assigned Bolna agent answers.

> [!NOTE]
>
> **IVR routing.** To let callers choose an option before an agent answers, pass an `ivr_config` object to the same [Set inbound agent](https://www.bolna.ai/docs/api-reference/inbound/agent) endpoint. This supports routing to different agents, language selection, and collecting digits. See Bolna's [IVR for inbound calls](https://www.bolna.ai/docs/inbound/ivr).

***

## Troubleshooting

| Issue | Solution |
| - | - |
| Authentication errors | Confirm the Auth ID and Auth Token in Bolna match the [Plivo console](https://cx.plivo.com/) exactly, with no trailing whitespace. |
| Outbound call uses the wrong caller ID | Confirm the agent's provider is set to **Plivo** and the connected phone number is the one you expect, in E.164 format. |
| Inbound call is not answered | Confirm the number is mapped to the correct Application, the Answer URL is the complete Bolna inbound URL including its query string, and an agent is assigned to the number in Bolna. |
| Call ends immediately | Check the Bolna account balance. Underfunded calls end with the `balance-low` status. |

**Debug logs.** For inbound issues, check the [Plivo logs](https://cx.plivo.com/voice/logs) first. For outbound issues, check the Bolna execution first. For hangup causes, see [Plivo hangup codes](https://plivo.com/docs/voice-agents/sip-trunking/troubleshooting/hangup-codes.md).

***

## Related

> **[Plivo Audio Streaming](https://plivo.com/docs/voice-agents/audio-streaming/overview.md)**
>
> How Plivo streams call audio to a voice agent.

> **[Application API](https://plivo.com/docs/account/api/application.md)**
>
> Create and manage Plivo Applications programmatically.

> **[Bolna Plivo docs](https://www.bolna.ai/docs/plivo)**
>
> Bolna's own Plivo configuration reference.

> **[Bolna API reference](https://www.bolna.ai/docs/api-reference/introduction)**
>
> Agents, calls, and inbound setup.