Implementing SIP Header Passthrough for Carrier-Originated Metadata and UUI Data

How-To-Articles
1

Implementing SIP Header Passthrough for Carrier-Originated Metadata and UUI Data

What This Guide Covers

This masterclass details the configuration and architectural logic required to pass custom SIP headers-such as carrier-originated metadata or User-to-User Information (UUI) strings-from a SIP trunk into Genesys Cloud Architect. By the end of this guide, you will be able to extract these headers in a call flow, use them for data-driven routing, and pass them downstream to external systems or agent scripts. This is essential for organizations migrating from legacy PBXs where critical interaction context (like an original IVR choice or a customer ID) is embedded in the SIP signaling.

Prerequisites, Roles & Licensing

Handling raw SIP headers requires administrative access to trunking configurations and Architect logic.

  • Licensing: Genesys Cloud CX 1, 2, or 3.
  • Permissions:
    • Telephony > Trunk > View/Edit
    • Architect > Flow > View/Edit
  • OAuth Scopes: telephony, architect.
  • Infrastructure: A BYOC Cloud or BYOC Premise SIP trunk.

The Implementation Deep-Dive

1. Configuring the Trunk for Header Passthrough

By default, Genesys Cloud ignores non-standard SIP headers for security and performance reasons. You must explicitly tell the trunk which headers to “whitelist” and make available to the Architect flow.

Configuration Step:

  1. Navigate to Telephony > Trunks and select your External SIP Trunk.
  2. Under Protocol > SIP Settings, look for the Custom SIP Headers section.
  3. Add the specific header names you expect from the carrier (e.g., X-Customer-ID, User-to-User).
  4. Set the Direction to Inbound.

The Trap:
Case Sensitivity. Many carriers send headers in varying cases (e.g., x-customer-id vs X-Customer-ID). Genesys Cloud treats these as literal strings.
The Solution: Add both variations to the whitelist or verify the exact signaling using a SIP diagnostic trace before configuring the trunk.

2. Extracting Headers in Architect using Get Call Data

Once the trunk is configured, the headers are stored as UUI Data or Participant Data on the interaction.

Architect Implementation Pattern:

  1. Use the Get Participant Data action.
  2. In the Attribute Name, enter the name of the SIP header exactly as it was whitelisted (e.g., X-Customer-ID).
  3. Assign the result to a variable (e.g., Task.CidFromSip).

Special Case: UUI (User-to-User Information)
UUI is a standard SIP header (User-to-User) used to pass hexadecimal or string data. Genesys Cloud has a dedicated variable for this: Call.UUIData. You do not need to use “Get Participant Data” for the standard UUI header; it is automatically populated if the carrier sends it correctly.

3. Parsing and Normalizing UUI Payloads

UUI data is often encoded in Hexadecimal or contains multiple key-value pairs separated by a delimiter (e.g., 12345;choice=2;status=active).

Architectural Reasoning:
Do not pass raw UUI strings to agents. Use Architect expressions to parse and normalize the data first. Use the Substring() and IndexOf() functions to extract specific segments.

Example Expression (Extracting a Customer ID from UUI):
Substring(Call.UUIData, 0, IndexOf(Call.UUIData, ";"))

4. Passing Headers to Outbound Legs (Transfer/Consult)

If you are transferring a call to an external partner, you may need to pass these headers back out.

The Trap:
Assuming inbound headers are automatically passed to outbound legs. They are not.
The Solution: In your Transfer to External Number block, use the UUI Data field or the Custom SIP Headers section to re-attach the data to the outbound INVITE.

Validation, Edge Cases & Troubleshooting

Edge Case 1: Header Length Restrictions

  • The failure condition: The call fails to connect, or the header data is truncated.
  • The root cause: SIP headers have a maximum length (typically 256 or 512 characters depending on the carrier and SBC).
  • The solution: If your payload is large, use a Reference ID instead. Store the large data blob in an external database and pass only the UUID in the SIP header. Use a Data Action in Architect to fetch the full context using that ID.

Edge Case 2: Multi-Part UUI Encoding

  • The failure condition: The data appears as gibberish (e.g., 04C8A1...).
  • The root cause: The carrier is using Hex Encoding (Common in Avaya/Cisco migrations).
  • The solution: Use a custom AWS Lambda Data Action to decode the hex string into ASCII before processing it in Architect. Genesys Cloud’s native string functions do not support hex-to-string conversion natively.

Official References