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

# Plivo

> Connect a Plivo account for BYOT inbound and outbound calling with bidirectional audio streaming.

# Use Plivo when you already own numbers and want Callaro to stream audio into your own telephony account.

Callaro treats Plivo as a **bring-your-own-telephony (BYOT)** provider. You connect your Plivo account, Plivo bills you for numbers and minutes, and Callaro handles agent routing, streaming, and call logs.

## Prerequisites

* Plivo Auth ID and Auth Token from the Plivo console.
* A public HTTPS SaaS API base URL so Plivo can reach telephony webhooks.
* A public `wss://` runtime host for `/ws/plivo`.
* At least one published, active agent to attach to inbound numbers.

## Setup workflow

<Steps>
  <Step title="Create the telephony connection">
    In Callaro, open **Telephony connections → New → Plivo** and save Auth ID plus Auth Token. Streaming settings are configured automatically.
  </Step>

  <Step title="Register or import the DID">
    Add the Plivo number as a phone number (E.164), link it to the Plivo connection, and assign the inbound agent.
  </Step>

  <Step title="Point Plivo at Callaro">
    Set the Plivo Application **Answer URL** to `https://<SAAS_API_PUBLIC_URL>/api/v1/webhooks/telephony/plivo` using `POST`.
  </Step>

  <Step title="Run inbound and outbound smoke tests">
    Confirm the webhook validates Plivo's V3 signature, the runtime receives the stream token, and `voice_sessions` show matching identifiers.
  </Step>
</Steps>

## Webhook contract

* Ingress path: `POST /api/v1/webhooks/telephony/plivo`
* Sample helper: `POST /api/v1/webhooks/telephony/plivo/sample`
* Authentication: Plivo **V3 signature** (`X-Plivo-Signature-V3` and `X-Plivo-Signature-V3-Nonce`) against the stored Auth Token
* No query-string token is required

On an inbound answer, Callaro returns bidirectional Stream XML that points at the runtime WebSocket with a short-lived stream token.

## Mapping guidance

* Persist the Plivo call UUID as the external reference on the voice session.
* Keep inbound agent assignment on the number, not only on the campaign.
* Treat Plivo minutes as provider-billed BYOT cost; they are not deducted from Callaro telephony credits.

## Validation checklist

* Inbound answer URL returns Stream XML and the call audio reaches the runtime.
* Outbound campaign or manual call creates a Plivo leg and a `voice_session`.
* Signature failures are rejected and do not create duplicate sessions.
* Recording and transcript retrieval still work after hangup.

## Known limits

* The runtime WebSocket host must be publicly reachable; private-only runtimes will fail stream setup.
* Number search/purchase depends on the Plivo account's enabled countries.
* Machine-detection callbacks use the same telephony webhook family and should be tested before enabling AMD in production.

## What to do next

* Review [`../api-reference/phone-numbers/overview`](../api-reference/phone-numbers/overview) for inventory and import flows.
* Review [`../guides/inbound-calling`](../guides/inbound-calling) before sending live inbound traffic to a Plivo DID.
* Review [`../api-reference/webhooks/overview`](../api-reference/webhooks/overview) for vendor webhook ingress and sample payloads.