A caller dials your Plivo number, Plivo routes it to your AI agent or PBX, and your endpoint sends REFER to hand off to a human agent. Plivo bridges the caller to the transfer target and disconnects your endpoint. The caller never re-dials.
Prerequisites
| Requirement | Description |
|---|
| Inbound SIP trunk | An inbound Plivo SIP trunk with your SIP endpoint configured as the termination URI. |
| Plivo phone number | A Plivo number linked to your inbound trunk so calls route to your endpoint. |
| REFER-capable endpoint | Your SIP endpoint (PBX, softphone, AI agent) must support sending SIP REFER requests. |
| Transfer destination | A Plivo number or reachable E.164 number to transfer the caller to. |
How it works
| Step | What happens |
|---|
| (1) Call established | The customer dials your Plivo number. Plivo routes the call to your SIP endpoint. Your endpoint 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 inbound trunk
- Go to cx.plivo.com/sip-trunking → Inbound Trunks
- Create or select an inbound trunk and set your SIP endpoint as the Primary URI
- Assign a Plivo number to the trunk — go to the trunk → Phone Numbers → link a number
Step 2: Answer the inbound call
When a customer dials your Plivo number, Plivo sends an INVITE to your SIP endpoint URI. Your endpoint responds 200 OK to answer.
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 (ending in .zt.plivo.com). 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. The original caller’s number is preserved as the caller ID presented to the transfer target.
What callers experience
- Caller ID preserved: The transfer target sees the original caller’s number, not your endpoint’s SIP URI.
- 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. |
| Transfer target sees wrong caller ID | For inbound transfers, the original caller’s number is always passed as caller ID — this is expected behaviour. |
