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

# Deploy a voice agent with Plivo Zentrunk

> Route Plivo calls through an authenticated SIP trunk.

## Overview

Connect an existing Plivo number to a Voiceflow Voice agent using **Zentrunk SIP trunking**. Plivo carries the telephone call; Voiceflow receives it at a hosted SIP address and runs the conversation, including speech recognition and spoken replies. This walkthrough configures an inbound Zentrunk and, when needed, a separate outbound Zentrunk. It does not require a media bridge or a Plivo number import in Voiceflow.

**Note:** 

**Other channels:** use the [Plivo SMS manual](/docs/guides/channels/sms/plivo) for text conversations. [Custom SIP](/docs/guides/channels/telephony/sip) explains the available Voiceflow connection types.

<a id="prepare-plivo"></a>

## Before you begin

Prepare the agent, controlled number and two independent credential sets.

| Owner | Required input |
| --- | --- |
| Agent builder | An editable [Voice agent](/docs/guides/studio/voice/first-phone-call), approved answers, voice input/output, and a test Environment with a recognizable greeting. |
| Voiceflow administrator | Phone-management access, available SIP allowance, project edit access and permission to resolve the project runtime API key for assignment. |
| Plivo administrator | Zentrunk access, an existing voice-enabled Plivo number, and permission to change its trunk. Record the current number/trunk association and primary/fallback URIs. |
| Tester | A separate phone you control and, for transfers, a teammate at an unforwarded support destination. |

Use a dedicated test number before changing customer routing. Obtain the SIP credentials you will configure below through your team's secure handoff. Plivo's REST Auth ID/Auth Token are account-management credentials; neither is the SIP password nor the Voiceflow runtime API key.

Give the agent a known support answer, a follow-up question it can handle and a clear end-of-call behavior. Connecting a carrier does not build these instructions or import [Knowledge](/docs/documentation/build/querying-the-knowledge-base).

<a id="connect-plivo"></a>

## Connect inbound calls

Route the Plivo number to an authenticated Voiceflow SIP hostname.

### 1. Create the Voiceflow endpoint

In [Agent studio](https://creator.voiceflow.com), open the Voice project's **Phone numbers → Create number → SIP → Voiceflow SIP**. Name the connection, choose **Credentials**, and enter a new SIP username/password that Plivo will supply when challenged. Choose **Create**, then copy the connection's complete **SIP address**.

Check its assigned Voice agent. Open **Environment**, select the test Environment and **Draft**, then **Save**. Workspace-level creation requires assigning the agent separately. Keep the connection ID from **Outbound call API → View** if your backend will place calls; it differs from the hostname.

### 2. Create a Plivo origination URI

In the [Plivo console](https://console.plivo.com), open **Zentrunk → Inbound Trunks → Create New Inbound Trunk**. Give the trunk a name. Under **Trunk Authentication**, choose **Add New URI** for the primary destination. Enter a label and the Voiceflow SIP hostname, enable **Authentication**, and enter the same inbound SIP username/password. Save with **Create URI**.

For this initial configuration use UDP on `5060`. The URI is the copied hostname, such as `connection-id.sip.example.com:5060`; replace this illustrative value with the actual Voiceflow hostname. Plivo supplies the dialled number in the SIP request. Do not substitute a resolved IP or use a registered extension. See [Plivo's inbound setup](https://www.plivo.com/docs/sip-trunking).

### 3. Save the trunk before attaching the number

Select the saved URI as **Primary URI**, inspect the enabled state and create the trunk. Retain an approved **Fallback URI** only if it leads to a working recovery destination. A fallback pointing back to the same number can loop. Confirm the saved primary hostname and authentication before attaching any number.

### 4. Link the controlled number

Select the existing number under **Current Phone Numbers** and choose **Link Selected Numbers**. Reopen the number and verify its inbound-trunk association. This changes real routing. Only inbound Zentrunks can be linked to numbers; creating an outbound trunk does not configure receipt of calls.

Every number sent to this SIP connection reaches its assigned agent/release. Use separate connections for different agents. Caller identity comes from the actual call, rather than the digest username; do not treat telephone Caller ID as proof of a customer's identity. The [SIP settings reference](/docs/api-reference/agent-runtime/voice/sip/settings#network-and-media) owns network and audio requirements.

<a id="outbound-and-transfers"></a>

## Configure callbacks and transfers

Create the separate carrier termination route before calling another destination.

### 1. Prepare the outbound Zentrunk

In **Zentrunk → Outbound Trunks**, create a trunk and attach a credential list containing a dedicated SIP username/password. Retain its generated termination hostname. If its authentication also requires an IP access list, have the administrator obtain the [Voiceflow signalling egress allowlist](/docs/api-reference/agent-runtime/voice/sip/settings#network-and-media) and configure it; media IPs are a different list. Follow [Plivo's outbound trunk setup](https://www.plivo.com/docs/sip-trunking) and verify permitted destination countries.

### 2. Configure Voiceflow's outbound peer

Open the Voiceflow SIP connection and enable **Outbound calls and transfers**. Save these values:

| Voiceflow field | Plivo value |
| --- | --- |
| Address | The generated outbound Zentrunk hostname, without `sip:`, a path or embedded port. |
| Protocol / Port | UDP / `5060` for this initial configuration. |
| Username / Password | The outbound trunk's SIP credentials, not its inbound origination-URI credentials. |
| Caller ID | An owned Plivo number in E.164, for example the actual US number replacing `+14155550100`. |

Plivo requires a Plivo number as outbound Caller ID. Match transport, codecs and any later TLS/SRTP change to [Zentrunk's specifications](https://www.plivo.com/docs/sip-trunking/concepts/technical-specifications) and [Voiceflow's encryption contract](/docs/api-reference/agent-runtime/voice/sip/settings#encrypted-audio).

### 3. Prepare the backend calling request

Have the Voiceflow administrator supply `SIP_CONNECTION_ID` from this connection's **Outbound call API → View** and `VF_API_KEY`, a runtime key authorized for the assigned project's read/version-read permissions. Set `TEST_RECIPIENT` to a separate E.164 phone you can answer. Keep these values on the backend. Run this only when ready to place the controlled call:

```sh
jq -n --arg to "$TEST_RECIPIENT" '{to:$to}' |
curl --fail-with-body --silent --show-error \
  "https://runtime-api.voiceflow.com/v1/sip-connection/$SIP_CONNECTION_ID/outbound" \
  -H "Authorization: $VF_API_KEY" -H 'Content-Type: application/json' --data-binary @-
```

HTTP `200` has an empty body and no call ID. Answer the phone and use the test below to establish an actual conversation. After an uncertain timeout, inspect Plivo call records before retrying. The [SIP outbound reference](/docs/api-reference/agent-runtime/voice/sip/outbound) owns the exact request and failures.

### 4. Configure a separate support destination

Open **Agent → Call forward** or add a Workflow **Call forward** step. Set the support destination and the condition for using it. For a transfer back through Plivo, choose **SIP address** and enter `sip:<support-number>@<your-trunk>.zt.plivo.com`, replacing the number with the separate E.164 support number and the domain with your actual Plivo trunk domain. Plivo blocks REFER targets on arbitrary other domains. A **Phone number** target uses a separate managed telephone-transfer operation; it does not establish carrier REFER interoperability. Plivo documents [inbound SIP REFER](https://www.plivo.com/docs/sip-trunking/concepts/sip-refer-inbound) separately from outbound calling. Verify the actual transfer with a teammate rather than inferring support from a successful callback. See [Transfer a phone caller](/docs/guides/studio/voice/transfer-calls) and the [SIP transfer contract](/docs/api-reference/agent-runtime/voice/sip/transfers).

<a id="test-calls"></a>

## Test the caller journey

Verify speech, repeated turns and termination through the real Plivo route.

### 1. Call the connected Plivo number

From a separate phone, call the controlled Plivo number. Expect the test Environment's greeting. Ask the agent a known support question and listen for a complete spoken answer.

### 2. Continue and end the conversation

Ask a follow-up that refers to the first answer. Expect the agent to retain the current conversation context. Hang up and confirm the call ends in Plivo's records and the matching Voiceflow [Transcript](/docs/documentation/measure/transcripts). Start a fresh call to check that the route still answers; do not assume a previous call remains active.

### 3. Verify each additional call direction

If configured, place one callback with the request above and confirm the expected Caller ID and two-way speech. In a separate inbound test, request the configured transfer; the teammate must hear and speak to the caller, then end the call. Check both legs in Plivo's **Zentrunk → Logs**. A transfer acceptance response alone does not establish pickup.

### The agent never answers

Check number association, primary URI and digest authentication.

Reopen the number's inbound Zentrunk and its Primary URI. Compare the complete Voiceflow hostname and both copies of the SIP credentials. Inspect Plivo's SIP logs for the failed INVITE. A challenge followed by an authenticated retry is expected; repeated challenges indicate a credential mismatch. Confirm Voiceflow's agent/Environment/version assignment separately.

### Audio, callback or transfer fails

Inspect the failing direction before changing a working inbound route.

For silence or one-way audio, compare negotiated codecs and SDP/media reachability using [SIP troubleshooting](/docs/api-reference/agent-runtime/voice/sip/troubleshooting). For callbacks, inspect the outbound trunk, credential list, destination permissions and Plivo-owned Caller ID. For a failed transfer, inspect REFER/phone-transfer handling and ensure the support destination is distinct from the incoming number. A refused transfer can terminate the agent call; keep the prior support route available.

<a id="release-and-maintain"></a>

## Release and maintain the route

Publish deliberately and retain a recoverable carrier configuration.

### 1. Select the reviewed release

[Publish the reviewed Environment](/docs/documentation/deploy/environments/publishing), change this connection's **Environment** setting to **Published**, and save. Publishing does not move a Draft-pinned connection. **All environments** follows Published traffic-split routing. Repeat the caller test on a fresh call before linking customer numbers.

### 2. Record and monitor the deployed route

Retain the number, inbound/outbound trunk IDs, primary/fallback URI IDs, Voiceflow SIP hostname/connection ID, agent and release. Monitor Plivo call failures and Voiceflow Transcripts together. Rotate each direction's credentials on both systems and retest with fresh calls.

### 3. Restore or retire safely

To roll back, restore the recorded Plivo number/trunk association and destination, then verify a call reaches the previous service. Route numbers away before unassigning or deleting the Voiceflow SIP connection. Do not delete an origination URI still used by an active primary or fallback route.
