Pass UUI data to Genesys Cloud during SIP transfers

When transferring calls to Genesys Cloud using SIP REFER, you may need to pass User-to-User Information (UUI) data. Genesys Cloud expects UUI data to be embedded directly in the Refer-To URI rather than as a separate SIP header.

The problem

When you use the headers parameter in TransferSIPParticipantRequest to add a User-to-User header, the header appears in the SIP REFER request but Genesys Cloud doesn't populate Call.UUIData from it. This is because Genesys expects UUI data embedded as a URI parameter in the Refer-To header itself.

What Genesys expects:

1
Refer-To: <sip:+15551234567@genesys-host.com?User-to-User=00FA1B2C%3Bencoding%3Dhex>

What happens with the headers parameter:

1
Refer-To: <sip:+15551234567@genesys-host.com>
2
User-to-User: 00FA1B2C;encoding=hex

The solution

Include the UUI data as a query parameter in the transfer_to field when calling TransferSIPParticipant. LiveKit preserves query parameters in the Refer-To URI.

Important: You must use the sip: URI format for this to work. LiveKit preserves query parameters when using sip: URIs. If you use the tel: format with a PSTN carrier, the transfer may fail depending on how the carrier handles UUI data in the URI.

Python

1
from livekit import api
2
from livekit.protocol.sip import TransferSIPParticipantRequest
3
from urllib.parse import quote
4

5
async def transfer_to_genesys_with_uui(
6
    room_name: str,
7
    participant_identity: str,
8
    destination_number: str,
9
    uui_data: str,
10
) -> None:
11
    """Transfer a call to Genesys Cloud with UUI data."""
12

13
    # URL-encode the UUI parameter value
14
    # The UUI format is: <hex-data>;encoding=hex
15
    uui_param = quote(f"{uui_data};encoding=hex", safe='')
16

17
    # Build the SIP URI with UUI as a query parameter
18
    transfer_to = f"sip:{destination_number}@your-genesys-edge.com?User-to-User={uui_param}"
19

20
    async with api.LiveKitAPI() as livekit_api:
21
        await livekit_api.sip.transfer_sip_participant(
22
            TransferSIPParticipantRequest(
23
                room_name=room_name,
24
                participant_identity=participant_identity,
25
                transfer_to=transfer_to,
26
                play_dialtone=False,
27
            )
28
        )

Node.js

1
import { SipClient } from 'livekit-server-sdk';
2

3
async function transferToGenesysWithUUI(
4
  roomName: string,
5
  participantIdentity: string,
6
  destinationNumber: string,
7
  uuiData: string
8
): Promise<void> {
9
  const sipClient = new SipClient(
10
    process.env.LIVEKIT_URL!,
11
    process.env.LIVEKIT_API_KEY!,
12
    process.env.LIVEKIT_API_SECRET!
13
  );
14

15
  // URL-encode the UUI parameter value
16
  const uuiParam = encodeURIComponent(`${uuiData};encoding=hex`);
17

18
  // Build the SIP URI with UUI as a query parameter
19
  const transferTo = `sip:${destinationNumber}@your-genesys-edge.com?User-to-User=${uuiParam}`;
20

21
  await sipClient.transferSipParticipant(
22
    roomName,
23
    participantIdentity,
24
    transferTo,
25
    { playDialtone: false }
26
  );
27
}

UUI data format

Genesys Cloud expects UUI data in hex-encoded format with an encoding indicator:

Example: Encoding a string as UUI

1
def string_to_uui_hex(data: str) -> str:
2
    """Convert a string to hex-encoded UUI data."""
3
    return data.encode('utf-8').hex()
4

5
# Example usage
6
context_data = "intent:billing,account:12345"
7
uui_hex = string_to_uui_hex(context_data)
8
# Result: "696e74656e743a62696c6c696e672c6163636f756e743a3132333435"

Verifying the transfer

To confirm UUI data is being passed correctly:

1. Capture SIP traffic: Use Wireshark or a similar tool to inspect the outgoing REFER request from LiveKit.
2. Check the Refer-To header: Verify the URI includes your User-to-User parameter with properly encoded data.
3. Verify in Genesys: Check that Call.UUIData is populated in your Genesys Cloud flow or Architect script.

Expected SIP REFER structure

1
REFER sip:caller@... SIP/2.0
2
Refer-To: <sip:+15551234567@your-genesys-edge.com?User-to-User=00FA1B2C%3Bencoding%3Dhex>
3
...

Genesys Cloud configuration

Ensure your Genesys Cloud Edge or BYOC trunk is configured to accept and process UUI data:

1. BYOC Premises: Configure your Edge to extract UUI from the Refer-To URI.
2. BYOC Cloud: Check your trunk settings for UUI handling.
3. Architect flows: Use the Call.UUIData variable to access the transferred UUI data.

Troubleshooting

UUI not appearing in Genesys

• Verify the User-to-User parameter is URL-encoded correctly in the transfer_to URI.
• Check that your Genesys trunk is configured to process UUI data from REFER requests.
• Confirm the hex encoding is valid (even number of hex characters).

Transfer fails with SIP error

• Ensure you're using a sip: URI, not a tel: URI. The tel: format may not preserve query parameters correctly, especially with PSTN carriers.
• Ensure the destination SIP URI is valid and the Genesys Edge is reachable.
• Check that your SIP trunk supports REFER transfers.
• Review Genesys Edge logs for rejection reasons.

Special characters in UUI data

URL-encode the entire UUI parameter value, including the ;encoding=hex suffix. The semicolon and equals sign must be percent-encoded (%3B and %3D).