WarmTransfer
sip media · published

Passing call context with SIP UUI and custom headers

Verified 2026-10-02 · 47 sources · tier 1–2

Also known as sip-x-headers, user-to-user-information, uui-header.

RFC 7433 (January 2015, Standards Track) defines the SIP User-to-User header field as a mechanism for transporting user-to-user call control information between the application that initiates a session and the application that accepts it 31. Platforms differ in which headers they read: the Amazon Chime SDK PSTN audio service accepts x- prefixed keys and User-to-User 2, Genesys Cloud reads User-To-User and falls back to x-User-To-User 15, and Dynamics 365 Contact Center supports SIP X headers for context transfer 10.

How the User-to-User header works

Under RFC 7433, the User-to-User header field may appear in INVITE and BYE requests 34. It may also appear in end-to-end responses to those requests, which are 1xx other than 100, 2xx, and 3xx 34. A sender may include multiple User-to-User header fields in one message, and receivers must be prepared to receive multiple 35.

RFC 7433 registers the SIP option tag 'uui' to indicate that a user agent supports and understands the User-to-User header field 37. RFC 7433 defines only one value for the 'encoding' parameter, 'hex', and leaves other encodings to future packages 32. When the 'purpose' parameter is absent, the ISDN UUI package (isdn-uui) applies by default 36. User agents must ignore UUI data from packages or encodings they do not understand 33.

The isdn-uui package

RFC 7434 defines the 'isdn-uui' package for the SIP User-to-User header, so that it can interwork with the ISDN User-to-User Signalling service 1 (implicit) 40. The sending application must put a protocol discriminator octet, as defined in ITU-T Q.931, as the first octet of isdn-uui data 43. RFC 7434 restricts the package to the initial INVITE and to BYE within an INVITE dialog 39. Re-INVITEs and other methods are not used for it 39. A receiving SIP entity must ignore an isdn-uui User-to-User header whose 'encoding' parameter is present with a value other than 'hex' 41.

X- prefixed headers

RFC 6648 (BCP 178, June 2012) says creators of new application-protocol parameters SHOULD NOT prefix their names with 'X-' or similar constructs 28. It also says implementations MUST NOT assume anything about a parameter's status based solely on the presence or absence of an 'X-' prefix 29. Despite this guidance, vendor platforms still document X- headers for context passing 2 10 26.

Size budgets

Source Stated size guidance
RFC 7433 Carrying UUI data elements of at least 129 octets is trivial, which satisfies REQ-11 30
RFC 7434 A limit of 128 octets of UUI data plus the protocol discriminator can be imposed on isdn-uui data 38
Genesys Cloud No character limit on a UUI string, but 128 characters or fewer is recommended because some systems discard longer data 12
Amazon Chime SDK PSTN audio SIP headers can be at most 2048 characters long 1
Dynamics 365 Contact Center SIP X header name is limited to 64 characters and value to 256 characters, with at most 5 SIP X headers per call 11 8

WarmTransfer's reading of the sources is that, because RFC 7433 hex encoding uses 2 characters per octet, a 128-octet isdn-uui payload plus protocol discriminator takes about 258 hex characters on the wire, so vendor '128 character' limits and RFC '128 octet' limits are not the same budget 27.

Platform differences

Genesys Cloud

Header selection and parsing. For inbound calls, Genesys Cloud looks first for a User-To-User header 15. It looks for an x-User-To-User header only if User-To-User is absent, and if both are present it uses User-To-User 15. If incoming UUI carries no encoding parameter, Genesys Cloud assumes hex encoding 14.

With the standard User-to-User header type, Genesys Cloud treats the first octet as the protocol discriminator and removes it before exposing the data 23. Genesys Cloud also accepts a User-to-User variant that gives the protocol discriminator in a separate pd parameter 18. In that case it does not remove the first data octet 18.

Genesys documents x-User-To-User as an AudioCodes proprietary header 26. According to Genesys, that header carries only the data, without the protocol discriminator or the standard purpose and content parameters, and is encoded as hex or ascii 26. Genesys advises encoding UUI as ASCII rather than hex when the data uses extended ASCII characters 128-255, because hex causes problems with those characters 13.

Trunk configuration. UUI is configured per external trunk under Admin > Telephony > Trunks > External Trunks > Protocol 24. The available settings are a UUI Passthrough toggle, header Type, Encoding Format, and Protocol Discriminator 24. The Protocol Discriminator field is not available when the X-User-To-User header type is selected 16.

A Static UUI value must have the protocol discriminator prepended and be encoded in ASCII or hex 22. When static and dynamic UUI share a header name, a Priority setting decides between them 22.

Architect flows. Inbound UUI lands in the read-only Call.UUIData variable 25. It does not automatically pass out of the flow, so a Set UUI Data action is needed to send it on 25. The Set UUI Data action sets UUI for transfer actions and disconnect actions 21. If the action is called more than once, the value from the last call is the one used 21.

UUI data does not transfer into secure call flows, and the Set UUI Data action is not available there 17. Invocation data is the documented alternative for secure call flows 17.

Transfers and remote stations. For REFER-based transfers, Genesys Cloud carries UUI as an escaped User-to-User header parameter inside the Refer-To URI 20. Genesys says UUI can persist to a PBX or SBC reached over a BYOC Cloud or BYOC Premises trunk that has UUI enabled 19. Genesys also says UUI is unlikely to persist if the far end is reached through the PSTN 19.

Amazon Chime SDK PSTN audio service

The SipHeaders field accepts only keys with the x- prefix, the User-to-User header, or the Diversion header 2. X-AMZN is a reserved header, and supplying it fails the action with an InvalidActionParameter error 3.

Amazon Connect

Amazon Connect exposes a fixed set of inbound telephony call metadata attributes under the JSONPath $.Media.Sip.Headers. 6. These attributes include P-Charge-Info, From, To, ISUP-OLI, JIP, and a Diversion-derived Call-Forwarding-Indicator 6. AWS states that this telephony metadata is not consistently available across telephony providers and cannot be guaranteed on every call 4.

We infer that inbound PSTN calls to Connect do not expose caller-supplied UUI as a standard attribute, because the metadata table does not list User-to-User or arbitrary X- headers 5.

Dynamics 365 Contact Center

Before SIP X header support, the SIP UUI field was the only way to pass call context in Dynamics 365 Contact Center, and it has a 128-character limit 9. SIP X header support for context transfer became generally available on 23 February 2026 and is enabled automatically 10. The 5-header limit applies to incoming calls and to external phone number transfers 8. SIP X header context transfer is described for environments that use Direct Routing telephony 7.

See also

See also SIP transactions dialogs and call setup.

See also Call transfer semantics REFER and Replaces.

See also PRI and TDM gateway interworking.

See also Genesys Cloud CX telephony and BYOC.

See also AudioCodes Mediant SBC.

Applicability

Applies to: Amazon Chime SDK, Genesys Cloud, Microsoft Dynamics 365 Contact Center, and Amazon Connect. Deployments: multi-tenant and any. Sources checked 2026-10-02. The standards evidence comes from RFC 7433 31, RFC 7434 40, and RFC 6648 (BCP 178, June 2012) 28. Dynamics 365 Contact Center SIP X header support has been generally available since 23 February 2026 10. That support is described for Direct Routing telephony environments 7. The Genesys Cloud persistence statements concern BYOC Cloud and BYOC Premises trunks with UUI enabled 19. The deployment model is not covered by the sources below.

What remains uncertain

The verbatim Webex Contact Center Add Headers section, including its header limit and telephony scope, is not covered by the sources below. Whether Webex Contact Center supports the User-to-User header, as opposed to X- headers, is not covered by the sources below. The hex encoding and length behavior of UUI on the Amazon Connect external voice transfer connector is not covered by the sources below. Whether Microsoft Teams Direct Routing passes through User-to-User and X- headers is not covered by the sources below. SIP Header Passing configuration and its add mod rem syntax in a current CVP guide are not covered by the sources below. How Genesys Cloud Architect reads and writes custom SIP X- headers is not covered by the sources below. UUI and SIP header context passing in other contact center platforms that no claim names are not covered by the sources below.

The only evidence here about the AudioCodes x-User-to-User header is Genesys's description of it 26. AudioCodes' own documentation of that header is not covered by the sources below. AudioCodes SBC message manipulation for UUI is also not covered by the sources below.

See also

Related to

Referenced by

Sources

  1. 1
    Amazon Chime SDK PSTN audio SIP headers can be at most 2048 characters long.
    Using SIP headers in the Amazon Chime SDK PSTN audio service · Section 'Using the SipHeaders field' · Checked 2026-10-02
  2. 2
    The Amazon Chime SDK PSTN audio SipHeaders field accepts only keys with the x- prefix, the User-to-User header or the Diversion header.
    Using SIP headers in the Amazon Chime SDK PSTN audio service · Section 'Using the SipHeaders field' · Checked 2026-10-02
  3. 3
    In the Amazon Chime SDK PSTN audio service X-AMZN is a reserved header, and supplying it fails the action with an InvalidActionParameter error.
    Using SIP headers in the Amazon Chime SDK PSTN audio service · Section 'Using the SipHeaders field' and failed CallAndBridge example · Checked 2026-10-02
  4. 4
    AWS states that Amazon Connect telephony metadata is not consistently available across telephony providers and cannot be guaranteed on every call.
    Use caller identification to personalize customer interaction · Section 'Troubleshoot issues' · Checked 2026-10-02
  5. 5
    The Amazon Connect telephony call metadata table does not list User-to-User or arbitrary X- headers, which suggests inbound PSTN calls to Connect do not expose caller-supplied UUI as a standard attribute.inferred
    Use caller identification to personalize customer interaction · Section 'Use telephony call metadata attributes' table (absence) · Checked 2026-10-02
  6. 6
    Amazon Connect exposes a fixed set of inbound telephony call metadata attributes (P-Charge-Info, From, To, ISUP-OLI, JIP, Diversion-derived Call-Forwarding-Indicator and others) under the JSONPath $.Media.Sip.Headers.<name>.
    Use caller identification to personalize customer interaction · Section 'Use telephony call metadata attributes' table · Checked 2026-10-02
  7. 7
    Dynamics 365 Contact Center SIP X header context transfer is described for environments using Direct Routing telephony.
    Enable SIP X header support for context transfer · Feature details, first paragraph · Checked 2026-10-02
  8. 8
    Dynamics 365 Contact Center allows at most five SIP X headers per call, for incoming calls and for external phone number transfers.
    Enable SIP X header support for context transfer · Feature details, technical limitations · Checked 2026-10-02
  9. 9
    Before SIP X header support, the SIP UUI field with a 128-character limit was the only way to pass call context in Dynamics 365 Contact Center.
    Enable SIP X header support for context transfer · Feature details, second paragraph · Checked 2026-10-02
  10. 10
    SIP X header support for context transfer in Dynamics 365 Contact Center became generally available on 23 February 2026, enabled automatically.
    Enable SIP X header support for context transfer · Availability table · Checked 2026-10-02
  11. 11
    In Dynamics 365 Contact Center a SIP X header name is limited to 64 characters and its value to 256 characters.
    Enable SIP X header support for context transfer · Feature details, technical limitations · Checked 2026-10-02
  12. 12
    Genesys Cloud imposes no character limit on a UUI string but recommends 128 characters or fewer because some systems discard longer data.
    Set UUI Data action · Paragraph on UUI length · Checked 2026-10-02
  13. 13
    Genesys advises encoding UUI as ASCII rather than hex when the data uses extended ASCII characters 128-255, because hex causes problems with those characters.
    UUI data formats · Section 'Encodings' and warning note · Checked 2026-10-02
  14. 14
    If incoming UUI carries no encoding parameter, Genesys Cloud assumes hex encoding.
    User to User Information (UUI) overview · Overview body, encoding paragraph · Checked 2026-10-02
  15. 15
    For inbound calls Genesys Cloud looks first for a User-To-User header and only if it is absent for an x-User-To-User header; if both are present it uses User-To-User.
    User to User Information (UUI) overview · Overview body, paragraph on inbound header detection · Checked 2026-10-02
  16. 16
    In Genesys Cloud trunk settings the Protocol Discriminator field is not available when the X-User-To-User header type is selected.
    Enable the User to User Information settings · Dynamic UUI settings, Protocol Discriminator note · Checked 2026-10-02
  17. 17
    UUI data does not transfer into Genesys Cloud secure call flows, and the Set UUI Data action is not available there; invocation data is the documented alternative.
    Set UUI Data action · Note on secure call flows · Checked 2026-10-02
  18. 18
    Genesys Cloud also accepts a User-to-User variant where the protocol discriminator is given in a separate pd parameter, and in that case it does not remove the first data octet.
    UUI data formats · Section 'User-to-User with pd parameter' · Checked 2026-10-02
  19. 19
    Genesys says UUI can persist to a PBX or SBC reached over a BYOC Cloud or BYOC Premises trunk with UUI enabled, but is unlikely to persist if the far end is reached through the PSTN.
    User to User Information (UUI) overview · Overview body, paragraph on remote stations · Checked 2026-10-02
  20. 20
    For REFER-based transfers Genesys Cloud carries UUI as an escaped User-to-User header parameter inside the Refer-To URI.
    UUI data formats · Section 'REFER format' · Checked 2026-10-02
  21. 21
    The Genesys Cloud Architect Set UUI Data action sets UUI for transfer actions and disconnect actions, and the value from the last call of the action is the one used.
    Set UUI Data action · Opening paragraphs · Checked 2026-10-02
  22. 22
    A Genesys Cloud Static UUI value must have the protocol discriminator prepended and be encoded in ASCII or hex; a Priority setting decides between static and dynamic UUI that share a header name.
    Enable the User to User Information settings · Static UUI settings (Static User Data section) · Checked 2026-10-02
  23. 23
    With the standard User-to-User header type Genesys Cloud treats the first octet as the protocol discriminator and removes it before exposing the data.
    UUI data formats · Section 'User-to-User' · Checked 2026-10-02
  24. 24
    Genesys Cloud UUI is configured per external trunk under Admin > Telephony > Trunks > External Trunks > Protocol, with a UUI Passthrough toggle, header Type, Encoding Format and Protocol Discriminator fields.
    Enable the User to User Information settings · Dynamic UUI settings (User to User Information section) · Checked 2026-10-02
  25. 25
    In Genesys Cloud, inbound UUI lands in the read-only Call.UUIData variable but does not automatically pass out of the flow; a Set UUI Data action is needed to send it on.
    Set UUI Data action · Paragraph on Call.UUIData · Checked 2026-10-02
  26. 26
    Genesys documents x-User-To-User as an AudioCodes proprietary header that carries only the data, without the protocol discriminator or the standard purpose and content parameters, encoded as hex or ascii.
    UUI data formats · Section 'x-User-To-User' · Checked 2026-10-02
  27. 27
    Because RFC 7433 hex encoding uses two characters per octet, a 128-octet isdn-uui payload plus protocol discriminator takes about 258 hex characters on the wire, so vendor '128 character' limits and RFC '128 octet' limits are not the same budget.inferred
    RFC 7434: Interworking ISDN Call Control User Information with SIP · Sections 3.1 and 9 combined with RFC 7433 Section 4 (encoding=hex) · Checked 2026-10-02
  28. 28
    RFC 6648 (BCP 178, June 2012) says creators of new application-protocol parameters SHOULD NOT prefix their names with 'X-' or similar constructs.
    RFC 6648: Deprecating the "X-" Prefix and Similar Constructs in Application Protocols (BCP 178) · Section 3 · Checked 2026-10-02
  29. 29
    RFC 6648 says implementations MUST NOT assume anything about a parameter's status based solely on the presence or absence of an 'X-' prefix.
    RFC 6648: Deprecating the "X-" Prefix and Similar Constructs in Application Protocols (BCP 178) · Section 2 · Checked 2026-10-02
  30. 30
    RFC 7433 states that carrying UUI data elements of at least 129 octets in the User-to-User header field is trivial, satisfying its size requirement REQ-11.
    RFC 7433: A Mechanism for Transporting User-to-User Call Control Information in SIP · Section 3 (requirements analysis, REQ-11) · Checked 2026-10-02
  31. 31
    RFC 7433 (January 2015, Standards Track) defines the SIP User-to-User header field as a mechanism for transporting user-to-user call control information between the application initiating a session and the application accepting it.
    RFC 7433: A Mechanism for Transporting User-to-User Call Control Information in SIP · Title, status line and Section 4 · Checked 2026-10-02
  32. 32
    RFC 7433 defines only one value for the User-to-User 'encoding' parameter, 'hex'; other encodings are left to future packages.
    RFC 7433: A Mechanism for Transporting User-to-User Call Control Information in SIP · Section 4 (encoding parameter) · Checked 2026-10-02
  33. 33
    RFC 7433 requires user agents to ignore UUI data from packages or encodings they do not understand.
    RFC 7433: A Mechanism for Transporting User-to-User Call Control Information in SIP · Section 4.1 · Checked 2026-10-02
  34. 34
    Under RFC 7433 the User-to-User header field may appear in INVITE and BYE requests and in end-to-end responses to them (1xx other than 100, 2xx and 3xx).
    RFC 7433: A Mechanism for Transporting User-to-User Call Control Information in SIP · Section 4.1 (header field table) · Checked 2026-10-02
  35. 35
    RFC 7433 allows a sender to include multiple User-to-User header fields in one message and requires receivers to be prepared to receive multiple.
    RFC 7433: A Mechanism for Transporting User-to-User Call Control Information in SIP · Section 4.1 · Checked 2026-10-02
  36. 36
    In RFC 7433, when the User-to-User 'purpose' parameter is absent the ISDN UUI package (isdn-uui) applies by default.
    RFC 7433: A Mechanism for Transporting User-to-User Call Control Information in SIP · Section 4 (purpose parameter) · Checked 2026-10-02
  37. 37
    RFC 7433 registers the SIP option tag 'uui' to indicate that a user agent supports and understands the User-to-User header field.
    RFC 7433: A Mechanism for Transporting User-to-User Call Control Information in SIP · Section 6.6 (IANA option tag registration) · Checked 2026-10-02
  38. 38
    RFC 7434 expects that a limit of 128 octets of UUI data plus the protocol discriminator can be imposed on isdn-uui data.
    RFC 7434: Interworking ISDN Call Control User Information with SIP · Sections 3.1 and 7 · Checked 2026-10-02
  39. 39
    RFC 7434 restricts the isdn-uui package to the initial INVITE and to BYE within an INVITE dialog; re-INVITEs and other methods are not used for it.
    RFC 7434: Interworking ISDN Call Control User Information with SIP · Sections 7 and 8 · Checked 2026-10-02
  40. 40
    RFC 7434 defines the 'isdn-uui' package for the SIP User-to-User header to interwork with the ISDN User-to-User Signalling service 1 (implicit).
    RFC 7434: Interworking ISDN Call Control User Information with SIP · Abstract and Sections 6-8 · Checked 2026-10-02
  41. 41
    RFC 7434 requires a receiving SIP entity to ignore an isdn-uui User-to-User header whose 'encoding' parameter is present with a value other than 'hex'.
    RFC 7434: Interworking ISDN Call Control User Information with SIP · Section 9 · Checked 2026-10-02
  42. 42
    RFC 7434 notes that UUI data exceeding what an ISDN interworking point supports can be discarded there without any error being signalled back to the sender.
    RFC 7434: Interworking ISDN Call Control User Information with SIP · Section 3.1 · Checked 2026-10-02
  43. 43
    RFC 7434 requires the sending application to put a protocol discriminator octet (per ITU-T Q.931) as the first octet of isdn-uui data.
    RFC 7434: Interworking ISDN Call Control User Information with SIP · Section 9 · Checked 2026-10-02
  44. 44
    Webex Contact Center Flow Designer exposes custom X-Headers from the incoming call through a 'Headers' output variable of the start activity (NewPhoneContact.Headers, now NewContact).
    Build and manage flows with Flow Designer · NewPhoneContact/NewContact activity, output variables · Checked 2026-10-02
  45. 45
    Cisco tells Webex Contact Center flow developers not to put sensitive PII such as full names, Social Security numbers, addresses or financial data in custom SIP headers.
    Build and manage flows with Flow Designer · Blind Transfer activity, Add Headers caution · Checked 2026-10-02
  46. 46
    Webex Contact Center Blind Transfer and Bridged Transfer activities have an Add Headers section that sends up to 20 custom key/value SIP headers in the outgoing INVITE.
    Build and manage flows with Flow Designer · Blind Transfer and Bridged Transfer activities, Add Headers section · Checked 2026-10-02
  47. 47
    Webex Contact Center custom X-Headers are supported only for organisations using Webex Calling with a Local Gateway as the contact center telephony option.
    Build and manage flows with Flow Designer · Blind Transfer activity, Add Headers note · Checked 2026-10-02

Documents

tier 1 standards and regulators

RFC 6648: Deprecating the "X-" Prefix and Similar Constructs in Application Protocols (BCP 178)

IETF / RFC Editor · 2012-06-01 · accessed 2026-10-02

tier 1 standards and regulators

RFC 7433: A Mechanism for Transporting User-to-User Call Control Information in SIP

IETF / RFC Editor · 2015-01-01 · accessed 2026-10-02

tier 1 standards and regulators

RFC 7434: Interworking ISDN Call Control User Information with SIP

IETF / RFC Editor · 2015-01-01 · accessed 2026-10-02

tier 2 current vendor documentation

Build and manage flows with Flow Designer

Cisco Systems, Inc. (Webex Help Center) · 2026-09-03 · accessed 2026-09-05

tier 2 current vendor documentation

Enable SIP X header support for context transfer

Microsoft · 2026-02-24 · accessed 2026-10-02

tier 2 current vendor documentation

Enable the User to User Information settings

Genesys · accessed 2026-09-25

tier 2 current vendor documentation

Set UUI Data action

Genesys · accessed 2026-09-25

tier 2 current vendor documentation

Use caller identification to personalize customer interaction

Amazon Web Services · accessed 2026-10-02

tier 2 current vendor documentation

User to User Information (UUI) overview

Genesys · accessed 2026-10-02

tier 2 current vendor documentation

Using SIP headers in the Amazon Chime SDK PSTN audio service

Amazon Web Services · accessed 2026-10-02

tier 2 current vendor documentation

UUI data formats

Genesys · accessed 2026-10-02

Cite this page

APA

WarmTransfer. (2026, October 2). Passing call context with SIP UUI and custom headers. WarmTransfer. https://warmtransfer.net/knowledge/sip-uui-context-passing

BibTeX

@misc{warmtransfer-sip-uui-context-passing,
  title  = {Passing call context with SIP UUI and custom headers},
  author = {{WarmTransfer}},
  year   = {2026},
  url    = {https://warmtransfer.net/knowledge/sip-uui-context-passing},
  note   = {Verified 2026-10-02}
}