SIP REFER Refer-To URI parameters stripped by LiveKit SIP bridge

Patrick Hurley
Thu, 23 Apr 2026 18:22:16 +0000
Telephony

Hi team — we’re integrating LiveKit voice agents with our telephony platform (Invoca) and running into an issue where tel: URI parameters in the
Refer-To header are being stripped by the LiveKit SIP bridge before they reach our downstream FreeSWITCH server.

What we’re doing:
Our voice agent calls transfer_participant with a Refer-To value of:
tel:+15559876543;x-ai-agent-outcome=transfer%3ATech%20Support

We can confirm via our agent logs that the SDK is sending this correctly (transfer_sip_refer_sending event shows the full URI with params).

What we see on the other side:
When the SIP REFER arrives at our FreeSWITCH, sip_refer_to contains only:
tel:+15559876543

The ;x-ai-agent-outcome=transfer%3ATech%20Support parameter is dropped somewhere in the LiveKit SIP infrastructure between the agent SDK and the
outbound REFER message.

Why we need this:
We’re using tel: URI parameters (per RFC 3966) to pass metadata like agent outcome back to our call platform during blind transfers. FreeSWITCH
reliably propagates sip_refer_to — the params just need to survive the LiveKit SIP bridge.

Environment: LiveKit Cloud, using livekit-agents Python SDK, SIP trunk via UDP to FreeSWITCH.

Is this a known limitation? Is there a way to preserve tel: URI parameters through the SIP REFER, or an alternative mechanism we should use?

3 posts - 2 participants