> ## 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

<div className="sipflow sipflow--vertical">
  <div className="sipflow__head">
    <span>Call flow</span>

    <span className="sipflow__head-right">
      <span className="sipflow__led" aria-hidden="true" />

      Bolna
    </span>
  </div>

  <ol className="sipflow__body">
    <li>
      <div className="sipflow__node">
        <span className="sipflow__node-body">
          <span className="sipflow__title">Phone Call</span>
        </span>
      </div>

      <div className="sipflow__link sipflow__link--bi" aria-hidden="true">
        <span className="sipflow__arrow sipflow__arrow--back" />

        <span className="sipflow__rail" />

        <span className="sipflow__arrow" />
      </div>

      <div className="sipflow__node">
        <span className="sipflow__node-body">
          <span className="sipflow__title">Plivo</span>
          <span className="sipflow__sub">Number + Application</span>
        </span>
      </div>

      <div className="sipflow__link sipflow__link--bi">
        <span className="sipflow__arrow sipflow__arrow--back" aria-hidden="true" />

        <span className="sipflow__rail" aria-hidden="true" />

        <span className="sipflow__edge-label">Answer URL</span>
        <span className="sipflow__edge-label sipflow__edge-label--return">Call audio</span>

        <span className="sipflow__arrow" aria-hidden="true" />
      </div>

      <div className="sipflow__node">
        <span className="sipflow__node-body">
          <span className="sipflow__title">Bolna</span>
          <span className="sipflow__sub">Voice agent</span>
        </span>
      </div>
    </li>
  </ol>
</div>

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](/docs/numbers/rent-india-numbers) |
| **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.

<Steps>
  <Step title="Add your Plivo credentials to Bolna" titleSize="h3">
    <Tabs>
      <Tab title="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**.
      </Tab>

      <Tab title="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.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Set Plivo as the agent's provider" titleSize="h3">
    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.
  </Step>
</Steps>

***

## Make outbound calls

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

<Steps>
  <Step title="Place a call" titleSize="h3">
    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"
    }'
    ```
  </Step>

  <Step title="Check the call" titleSize="h3">
    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).
  </Step>
</Steps>

***

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

<Steps>
  <Step title="Get the inbound URL from Bolna" titleSize="h3">
    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).
  </Step>

  <Step title="Create an application in Plivo" titleSize="h3">
    <Tabs>
      <Tab title="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                   |
      </Tab>

      <Tab title="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](/docs/account/api/application) 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>"
        }'
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Connect your phone number" titleSize="h3">
    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**.
  </Step>

  <Step title="Test" titleSize="h3">
    Call your Plivo number. The assigned Bolna agent answers.
  </Step>
</Steps>

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

***

## 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](/docs/voice-agents/sip-trunking/troubleshooting/hangup-codes).

***

## Related

<CardGroup cols={2}>
  <Card title="Plivo Audio Streaming" icon="audio-lines" href="/docs/voice-agents/audio-streaming/overview">
    How Plivo streams call audio to a voice agent.
  </Card>

  <Card title="Application API" icon="code" href="/docs/account/api/application">
    Create and manage Plivo Applications programmatically.
  </Card>

  <Card title="Bolna Plivo docs" icon="book" href="https://www.bolna.ai/docs/plivo" arrow={true}>
    Bolna's own Plivo configuration reference.
  </Card>

  <Card title="Bolna API reference" icon="book" href="https://www.bolna.ai/docs/api-reference/introduction" arrow={true}>
    Agents, calls, and inbound setup.
  </Card>
</CardGroup>