Your AI agent or PBX places an outbound call through Plivo, then sends REFER mid-call to hand off to a human agent. Plivo bridges the caller to the transfer target and disconnects your endpoint. No re-dial, no dropped call.
Prerequisites
| Requirement | Description |
|---|
| Outbound SIP trunk | An outbound Plivo SIP trunk with your endpoint registered via IP ACL or credentials. |
| REFER-capable endpoint | Your SIP endpoint (PBX, softphone, AI agent) must support sending SIP REFER requests. |
| Phone numbers | At least two Plivo numbers — one for the customer leg, one as the transfer destination. |
How it works
| Step | What happens |
|---|
| (1) Call established | Your endpoint dials the customer via your Plivo SIP trunk. The customer answers. |
| (2) REFER | Your endpoint sends REFER with the transfer target’s number in the Refer-To header. |
| (3) Accepted | Plivo responds 202 Accepted and sends NOTIFY 100 Trying. |
| (4) New leg | Plivo places a new call to the transfer target. |
| (5) Connected | Transfer target answers. Plivo sends NOTIFY 200 OK. |
| (6) BYE | Plivo disconnects your endpoint. Customer and transfer target continue the call. |
Step-by-step guide
Step 1: Set up your outbound trunk
- Go to cx.plivo.com/sip-trunking → Outbound Trunks
- Click Create New Outbound Trunk, create a credentials list, and save
- Copy the Termination SIP Domain — for example,
XXXXXXXXXXXX.zt.plivo.com
Step 2: Place the outbound call
Your endpoint dials the customer via your SIP trunk domain:
sip:<customer-number>@XXXXXXXXXXXX.zt.plivo.com
Step 3: Send the REFER
When ready to hand off, send a REFER with the transfer target in the Refer-To header.
Refer-To header format:
Refer-To: <sip:+14155551234@XXXXXXXXXXXX.zt.plivo.com>
Use your SIP trunk domain in the Refer-To header. Transfers to other domains or arbitrary SIP URIs are blocked.
REFER sip:trunk@XXXXXXXXXXXX.zt.plivo.com SIP/2.0
Via: SIP/2.0/UDP 192.168.1.100:5060;branch=z9hG4bK-524287-1
From: <sip:endpoint@pbx.example.com>;tag=12345
To: <sip:trunk@XXXXXXXXXXXX.zt.plivo.com>;tag=67890
Call-ID: 1-12345@192.168.1.100
CSeq: 1 REFER
Contact: <sip:endpoint@192.168.1.100:5060>
Refer-To: <sip:+14155551234@XXXXXXXXXXXX.zt.plivo.com>
Max-Forwards: 70
Content-Length: 0
Step 4: Handle NOTIFY messages
After 202 Accepted, Plivo sends NOTIFY messages to report transfer progress. Your endpoint must respond to each NOTIFY with 200 OK.
| NOTIFY status | Meaning | What to do |
|---|
SIP/2.0 100 Trying | Plivo is calling the transfer target | Show “Transferring…” in your UI. Keep the call active. |
SIP/2.0 180 Ringing | Transfer target is ringing | Optionally relay ring-back tone to the caller. |
SIP/2.0 200 OK | Caller and target are connected | You may hang up your leg (or wait for Plivo’s BYE). |
SIP/2.0 4xx / 5xx | Transfer failed | Caller is still on your line — retry or continue the call. |
Do not send BYE before receiving NOTIFY 200 OK. Sending BYE early drops the caller before the transfer completes.
Step 5: Call continues between customer and transfer target
Plivo bridges the caller to the transfer target and sends your endpoint a BYE.
What callers experience
- During the transfer: The caller hears ring-back from the transfer target (180 Ringing) until the target answers.
- If the transfer fails: The caller remains on your leg. You can retry with a different number or continue the conversation.
- Music on hold: To play hold music while the transfer leg is establishing, play audio from your endpoint before sending REFER.
Response codes
| Code | Meaning |
|---|
202 Accepted | REFER accepted — transfer is in progress |
400 Bad Request | Missing or malformed Refer-To header |
403 Forbidden | Refer-To domain is not a valid Plivo SIP trunk domain, or transfer target is a private IP |
Troubleshooting
| Symptom | Check |
|---|
| 403 Forbidden | Verify the Refer-To domain ends in .zt.plivo.com. Ensure the target is not a private IP. |
| 400 Bad Request | Verify the Refer-To header uses E.164 format: sip:+14155551234@trunk.zt.plivo.com. |
| 202 Accepted but caller is dropped | Your endpoint sent BYE before receiving NOTIFY 200 OK. Wait for NOTIFY 200 OK first. |
| 202 Accepted but no NOTIFY received | Ensure your endpoint listens on the same IP/port it advertised in the Contact header. |
| Transfer fails (NOTIFY 4xx/5xx) | Check that the destination is valid, reachable, and not busy. Verify account balance. |
| Transfer to international number returns 403 | Enable that destination under Geo Permissions. |
| No audio after transfer | Codec mismatch between legs. Contact Plivo Support with the Call-ID. |
