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:

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

What happens with the headers parameter:

Refer-To: <sip:+15551234567@genesys-host.com>
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

from livekit import api
from livekit.protocol.sip import TransferSIPParticipantRequest
from urllib.parse import quote

async def transfer_to_genesys_with_uui(
    room_name: str,
    participant_identity: str,
    destination_number: str,
    uui_data: str,
) -> None:
    """Transfer a call to Genesys Cloud with UUI data."""

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

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

    async with api.LiveKitAPI() as livekit_api:
        await livekit_api.sip.transfer_sip_participant(
            TransferSIPParticipantRequest(
                room_name=room_name,
                participant_identity=participant_identity,
                transfer_to=transfer_to,
                play_dialtone=False,
            )
        )

Node.js

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

async function transferToGenesysWithUUI(
  roomName: string,
  participantIdentity: string,
  destinationNumber: string,
  uuiData: string
): Promise<void> {
  const sipClient = new SipClient(
    process.env.LIVEKIT_URL!,
    process.env.LIVEKIT_API_KEY!,
    process.env.LIVEKIT_API_SECRET!
  );

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

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

  await sipClient.transferSipParticipant(
    roomName,
    participantIdentity,
    transferTo,
    { playDialtone: false }
  );
}

UUI data format

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

Example: Encoding a string as UUI

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

# Example usage
context_data = "intent:billing,account:12345"
uui_hex = string_to_uui_hex(context_data)
# 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

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

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).