Troubleshoot Transfer to Human Agent

What: Test a transfer from your AI agent to a human agent, and fix one that fails or has no audio.
Start with: a transfer to a phone number. If it connects, the fault is on the SIP path.

The setup for each option is on its own page: DID forward, SIP auth forward, and Multiparty Call.

Test Your Transfer

Transfer to a phone number first

Point a test transfer at a phone number that reaches the same team. If this connects, your XML, your application, and your Plivo account are all working — which narrows any later failure to the SIP path.

Transfer to the SIP endpoint

Run the same transfer against your SIP endpoint. A failure here, after the phone number transfer succeeded, points at the firewall or the SIP credentials rather than at your agent logic.

Check audio in both directions

Speak from each end. Audio in one direction only means the RTP media ranges are whitelisted in one direction only.

Confirm your application reads DialStatus

Your Dial action URL should receive DialStatus and DialHangupCause, so your application can fall back or inform the caller when a handoff fails.

Hangup Causes and Dial Status

When a transfer fails, the Dial action URL and hangup callback include specific values:

HangupCauseName	Code	DialStatus	Meaning
`sip_auth_failed`	`4240`	`failed`	SIP credentials were rejected by the remote endpoint
`sip_auth_timeout`	`4250`	`timeout`	Remote endpoint did not respond to the digest challenge
`no-answer`	—	`no-answer`	Agent did not pick up within the dial timeout
`busy`	—	`busy`	Agent endpoint is busy

Your agent application receives DialStatus and DialHangupCause on the Dial action URL, so it can detect a failed handoff and respond (e.g., retry with a different endpoint, fall back to a phone number, or inform the caller). Every hangup code is listed in Hangup Causes.

Troubleshooting

Issue	Solution
Transfer never arrives, and nothing appears in your contact center’s logs	Only the RTP media ranges are whitelisted, so the INVITE is dropped before it arrives. Whitelist the External SIP endpoints on port 5060, and confirm your endpoint is listening on that port
The Dial action URL reports an empty `DialBLegUUID`	Nobody answered, so no B-leg was created. Check the SIP URI in `<User>` against the Dial XML reference, then check that your endpoint is reachable
Transfer fails with `sip_auth_failed` (`4240`)	Verify the SIP credentials match exactly. Check your contact center’s auth realm. Some platforms authenticate by IP address instead of digest — if yours does, whitelist Plivo’s addresses rather than sending credentials
Transfer fails with `sip_auth_timeout` (`4250`)	Your endpoint is unreachable, or its SIP service isn’t running. Check both before re-testing credentials
Agent answers, but there’s no audio	Configure your SIP endpoint to advertise its public IP address. A private address in its `Contact` header or SDP leaves Plivo’s audio with nowhere to send to
Call is rejected before the agent’s phone rings	No shared audio codec. Offer PCMU or PCMA on your SIP endpoint
Audio works in one direction only	The RTP media ranges are whitelisted in one direction only. Add a rule for each direction
Call connects, but the line stays open after one side hangs up	Plivo’s in-dialog `BYE` may be sent from a different source port than the one that opened the dialog. A firewall rule pinned to source port 5060 drops it. Whitelist Plivo’s addresses without pinning a source port
Transfer XML doesn’t run while your AI agent’s `<Stream>` with `keepCallAlive="true"` is open	Close your AI agent’s WebSocket when it decides to transfer. If transfers still drop the call or never run, use a Multiparty Call
In a Multiparty Call warm transfer, the caller hears your AI agent brief the human agent	Hold the caller with `hold` set to `true`, not `mute`. A muted participant still hears everyone in the Multiparty Call
In a Multiparty Call, the held caller hears silence instead of hold music	Make your `customerHoldMusicUrl` return XML with a `<Play>` element, not an audio file. See Custom Hold Music
Caller hears silence during ring	Use the `dialMusic` attribute on `<Dial>` to play hold music while the agent is being reached

Transfer to Human Agent — When to transfer, and how to choose an approach
Option 1: DID Forward — Transfer to a phone number
Option 2: SIP Auth Forward — Transfer to a SIP endpoint with credentials
Option 3: Multiparty Call — Cold or warm transfer in a Multiparty Call
What Your Contact Center Must Do — Firewall and SIP settings for your contact center
Hangup Causes — Every hangup code and its meaning

Concepts

Integration Guides

Workflows

Deploy

Reference

Troubleshoot Transfer to Human Agent

Test Your Transfer

Hangup Causes and Dial Status

Troubleshooting

​Test Your Transfer

​Hangup Causes and Dial Status

​Troubleshooting

​Related

Test Your Transfer

Hangup Causes and Dial Status

Troubleshooting

Related