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

Telephony
1

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?

2

Follow up message. It was suggested that not wrapping transfer_to in < > brackets was the issue. Ran another set of tests with:

{
   'destination': 'Tech Support',
   'transfer_to': '<tel:+15559876543;x-ai-agent-outcome=transfer%3ATech%20Support>',
   'phone_number': '+155 59876543',
   'participant': 'sip\_+17349915093',
   'participant_sid': 'PA_8GejPyYKuDW4',
   'event': 'transfer_sip_refer_sending',
   'logger': 'voice_agent.agents.tools.transfer_call',
   'level': 'info',
   '@timestamp': '2026-04-24T02:39:05.020491Z'
}

And then the response to our FreeSWITCH was observed using:

ngrep -qT -W byline -d any 'REFER' 'udp and port 5060'

as

U +12.990509 161.115.178.125:5060 -> 10.203.39.121:5060
REFER sip:mod_sofia@3.86.178.113:5060 SIP/2.0.
Record-Route: <sip:161.115.178.125:5060;sipfe;transport=udp;lr>.
Record-Route: <sip:10.35.164.7:40004;sipfe;transport=tcp;lr>.
Via: SIP/2.0/UDP 161.115.178.125:5060;branch=z9hG4bK.d4fff2124c3567bc9392e3f0.sipfe.
Via: SIP/2.0/TCP 10.35.164.7:40004;branch=z9hG4bK.d4fff2124c3567bc9392e3f0.sipfe.
Via: SIP/2.0/TCP 161.115.179.25:9000;branch=z9hG4bK.5E2yZps1DRQVdhcp;alias.
Max-Forwards: 69.
Call-ID: 34306a3e-ba2d-123f-699e-12962279f1d9.
Contact: <sip:161.115.179.25:9000;transport=tcp>.
Refer-To: <tel:+15559876543>.
Allow: INVITE, ACK, CANCEL, BYE, NOTIFY, REFER, MESSAGE, OPTIONS, INFO, SUBSCRIBE.
X-AI-Agent-Outcome: transfer:Tech Support.
Content-Length: 0.
CSeq: 113946155 REFER.
From: <sip:+17349915093@2lddta7nrg5.sip.livekit.cloud:5060;transport=udp>;tag=SCL_VDDyG8mrhaGm.
To: "Patrick" <sip:+17349915093@3.86.178.113>;tag=N4y26522am16g.

Noting specifically:

Refer-To: <tel:+15559876543>

Which lost the x-ai-agent-outcome parameter.
Thanks for your time and attention.