How-to

Plivo integration

Integrate Plivo for cost-effective outbound campaigns and inbound call handling with PCM audio streaming.

Prerequisites

Plivo account — Sign up at plivo.com and obtain your Auth ID and Auth Token.
Phone numbers — Purchase Plivo numbers with voice capability in your target regions.
Webhook access — Ensure your Breeze Buddy server is publicly accessible.
Register numbers — Add your Plivo numbers via the Numbers API with provider: "plivo".

Environment Variable	Description
`PLIVO_AUTH_ID`	Your Plivo Auth ID
`PLIVO_AUTH_TOKEN`	Your Plivo Auth Token

Outbound calls

calls.create()

Customer Answers

Plivo hits answer_url

Start Recording + AIC

Pod Allocation

WebSocket Audio

API call — calls.create() with answer_url pointing to /plivo/answer
Customer answers — Plivo hits the answer_url webhook
Recording + noise cancellation — Recording starts and AIC noise enhancement is optionally enabled
Pod allocation — Smart Router allocates a dedicated pod (production)
WebSocket stream — XML response establishes a bidirectional PCM audio stream

Answer webhook

POST /plivo/answer Called by Plivo when the customer answers. Returns XML with the WebSocket stream URL.

plivo-answer-response.xml

xml

<Response>
  <Stream streamTimeout="86400" keepCallAlive="true"
    contentType="audio/x-l16;rate=8000"
    bidirectional="true"
    url="wss://your-domain.com/agent/voice/breeze-buddy/ws/plivo">
    lead_id
  </Stream>
</Response>

Audio encoding

Plivo uses PCM L16 at 8 kHz — a key difference from Twilio and Exotel which use μ-law encoding.

Parameter	Value
Encoding	PCM L16 (linear 16-bit)
Sample Rate	8000 Hz
Content Type	`audio/x-l16;rate=8000`
Stream Timeout	86400 seconds (24h)
Bidirectional	`true`

PCM vs μ-law

PCM L16 provides higher fidelity than μ-law at the same sample rate, but uses more bandwidth. The pipeline auto-detects the encoding based on the provider.

Callbacks

POST /plivo/callback/status Call hangup notification — triggers retry logic and status updates.

POST /plivo/callback/details Recording URL delivery after the call ends.

POST /plivo/callback/transfer Warm transfer status — reports whether the transfer succeeded or failed.

Warm transfer

Plivo uses calls.transfer() to redirect the active call to a dial-up webhook:

AI triggers transfer

calls.transfer() → /dial-up

Webhook returns Dial XML

Customer bridged to agent

AI disconnects

POST /plivo/dial-up Called by Plivo after calls.transfer(). Returns Dial XML to connect the customer to the transfer target.

plivo-dial-response.xml

xml

<Response>
  <Dial callerId="{outbound_number}">
    <Number>{transfer_number}</Number>
  </Dial>
</Response>

Recording

Unlike Twilio’s native record=True, Plivo requires recording to be started explicitly via the API:

plivo_recording.py

python

plivo_client.calls.record(
    call_uuid=call_uuid,
    callback_url=f"{base_url}/plivo/callback/details"
)

Cost Optimization

Plivo generally offers lower per-minute rates than Twilio for voice calls, especially in international markets. Compare pricing for your target regions before selecting a provider.

Next steps

Inbound calls Route incoming calls with IVR.Warm transfer Hand off to a human agent mid-call.Webhooks Receive call lifecycle events.Voice pipeline Tune STT, TTS, and VAD for phone calls.

Was this helpful?

Edit on GitHub