i cant seem to make the agent recieve or send sip headers when transferringa call. I am calling agent_a's phone number, and making agent_a execute transfer call to agent_b, and sending sip headers to the transfer_sip_participant. I dont see agent_b recieving any header.

Thanks for reaching out, Cesar. I'm an AI assistant and I'm here to help. Give me a moment while I research this topic.

im using this 'from livekit.protocol import sip as proto_sip request = proto_sip.TransferSIPParticipantRequest( participant_identity=participant_identity, room_name=job_context.room.name, transfer_to=transfer_to, play_dialtone=True, headers={"X-CallStatus": "Transferred", "X-CallerId": agent_did}, ) response = await job_context.api.sip.transfer_sip_participant(request)'

Thanks — this is helpful. You showed the exact code you’re calling, so I’ll explain what’s happening with that

headers

field and give practical alternatives you can use to make agent_b receive the transfer context. What’s happening with your code • The

headers

you set on

TransferSIPParticipantRequest

add custom SIP headers to the SIP REFER that LiveKit sends to perform the transfer. • However, those headers are not guaranteed to appear to the transferred participant (agent_b) in the new leg: ◦ Intermediary SIP proxies/trunks can strip or ignore custom headers in REFER messages. ◦ The new session for agent_b does not automatically inherit headers from the REFER. LiveKit does not map those REFER headers into agent_b’s LiveKit participant attributes by default. ◦ For some platforms (e.g., Genesys Cloud), UUI must be embedded in the Refer-To URI rather than relying on arbitrary headers. Consequence • agent_b will not reliably receive

X-CallStatus

,

X-CallerId

, or similar custom headers when you rely only on

TransferSIPParticipantRequest.headers

. Workarounds and recommended approaches 1. Embed context in the transfer URI (best when supported) ◦ Put the data into the

transfer_to

SIP URI as query parameters (or UUI for Genesys). Example pattern: ▪︎

<sip:+15551234@sip.provid>er.com?User-to-User=<encoded-uui>

or

?X-CallStatus=Transferred&X-CallerId=...

◦ Ensure the downstream SIP gateway/endpoint will parse query params from the Refer-To URI and deliver them to agent_b. 1. Map incoming headers to LiveKit participant attributes at the trunk ◦ Configure your SIP trunk to map incoming SIP headers into participant attributes (attributes -> headers or headers -> attributes depending on flow). ◦ When agent_b’s INVITE arrives, those mapped attributes will be available as LiveKit participant attributes that the receiving client can read. 1. Send context out-of-band ◦ Use a shared datastore, message bus, or a webhook to record transfer context (call id, status, caller id). ◦ Notify agent_b’s client (via your backend or a data channel) so the agent application receives the transfer metadata directly. 1. Originate the new leg with headers (if possible) ◦ If you can create the outbound leg to agent_b yourself (via CreateSIPParticipantRequest or other outbound API that supports headers), add the needed headers on call creation rather than relying on REFER. Debugging steps to confirm behavior 1. Capture SIP traces (e.g., Wireshark) during a transfer and inspect the REFER / Refer-To header contents. 2. Verify whether your SIP trunk/proxies are removing headers from REFER messages. 3. Check whether the Refer-To URI contains your query params/UUI and whether the downstream PBX forwards them as headers or into the INVITE to agent_b. 4. Share the actual

transfer_to

value (redact secrets) if you want me to confirm the URI encoding. If you tell me: • Which SIP provider or contact center (Genesys, Five9, custom PBX) agent_b is on, • The

transfer_to

string you’re using (redact sensitive parts), I’ll recommend the most practical next step (URI formatting for Genesys UUI, trunk mapping instructions to get attributes into LiveKit, or an out-of-band pattern). Sources: Pass UUI data to Genesys Cloud during SIP transfers | LiveKit | How to do call transfers with Five9 | LiveKit

we are using telnyx and livekit's sip cloud

Thanks — that helps a lot. You’re using Telnyx + LiveKit’s SIP Cloud, and you showed the exact request you’re sending. I’ll be direct: the behavior you’re seeing is expected — custom SIP headers on

TransferSIPParticipantRequest

will not reliably arrive at the transferred-to agent (agent_b) when using LiveKit + Telnyx. Why this is happening •

TransferSIPParticipantRequest.headers

adds headers to the SIP REFER that LiveKit sends, but those headers: ◦ Can be stripped or ignored by SIP intermediaries (trunks, proxies) such as Telnyx. ◦ Are not mapped automatically into the new INVITE/participant attributes that agent_b receives in the new session. • LiveKit does not automatically convert REFER headers into LiveKit participant attributes for the receiving agent, so agent_b won’t see them in the new room/session. What will work (recommended options) 1. Embed the data in the transfer URI (recommended for Telnyx) ◦ Put your context into the Refer-To URI as query parameters or UUI. Example pattern: ▪︎

<sip:+1234567890@your-telnyx-domain.com>?User-to-User=<url-encoded-data>

◦ Pack your fields (X-CallStatus, X-CallerId) into a single UUI string and URL-encode it. ◦ Confirm Telnyx is configured to parse the Refer-To query or User-to-User parameter and forward that info to the endpoint. ◦ This is the most reliable way to get call context through a REFER flow when working with PSTN providers. 1. Use participant attributes / trunk mapping ◦ Configure your SIP trunk or LiveKit trunk mapping to convert incoming headers/URI params into LiveKit participant attributes. ◦ Set attributes before transfer so the receiving side can read them after the new leg is established. ◦ Note: this requires trunk configuration and won’t magically make REFER headers appear in the new INVITE without the gateway mapping them. 1. Out-of-band context delivery (most robust) ◦ Store transfer context in your backend (DB, cache, message bus) keyed by call id. ◦ Notify agent_b’s client (via your backend webhook or a signaling channel) when the transfer happens so the agent UI receives metadata directly. ◦ This avoids relying on SIP carrier behavior. 1. Originate the new leg with headers (if you can) ◦ If you can create the outbound call to agent_b yourself (instead of relying on REFER), use the outbound API that supports headers so the INVITE contains the headers you need. Concrete debugging steps to try now 1. Convert your

transfer_to

to a

sip:

URI and include UUI or query params. Example: ◦ Build a UUI string:

X-CallerId=15551234567;X-CallStatus=Transferred

◦ URL-encode and place in the URI:

<sip:+1555xxxx@telnyx-domain.com>?User-to-User=<encoded>

1. Capture SIP traffic (Wireshark or Telnyx SIP logs) during the transfer and inspect: ◦ The REFER and Refer-To header contents. ◦ Whether Telnyx rewrites or strips headers. ◦ What INVITE agent_b actually receives. 1. If you want, paste the (redacted)

transfer_to

string you plan to use and I’ll confirm the URI encoding/format for you. If you prefer, I can: • Show a small code snippet to construct a URL-encoded UUI

transfer_to

in Python. • Help verify Telnyx config points to extract User-to-User from Refer-To. Which would you like to do next? Sources: Agents telephony integration | LiveKit Documentation | Pass UUI data to Genesys Cloud during SIP transfers | LiveKit | How to do call transfers with Five9 | LiveKit | Outbound Calling Script | LiveKit Documentation