Share via

Configure SIP X-headers for voice-enabled agents

This article explains how to configure Session Initiation Protocol (SIP) X-headers for incoming and outgoing calls in Copilot Studio voice-enabled agents for use in Dynamics 365 Contact Center.

SIP X-headers enable you to pass custom metadata between telephony systems and your voice-enabled agents. Dynamics 365 Contact Center voice-enabled agents support both incoming and outgoing X-headers. This configuration allows seamless data exchange during call transfers and routing.

Prerequisites

Configure incoming X-headers

Incoming X-headers contain metadata passed from external telephony systems to your voice-enabled agent. To receive and use this data, you must configure a Parse Value node to extract X-header information from the Conversation.SipXHeader system variable.

Incoming X-header requirements

  • Maximum count: Five X-headers per incoming call.

  • Naming requirement: All X-header names must start with x-.

    Note

    In Copilot Studio, all incoming X-headers must start with lower case x-, even if the external system sending the X-header is using an upper case X-. The outgoing X-header defined in Copilot Studio can be either lower case or upper case, depending on what case the external system is expecting.

  • Name length: Up to 64 characters.

  • Value length: Up to 256 characters.

  • A JSON schema is required for all expected X-headers.

  • Update the JSON schema when X-header names change.

  • Channel data dependency: X-headers must be present in Conversation.SipXHeader.

Add Variable Management - Parse Value node

  1. Navigate to your voice-enabled agent's topic.

  2. Add a new topic node.

  3. Select Variable management and select Parse value.

    Screenshot of the Variable management option, highlighting Parse value.

Configure the Parse Value node

  1. From the System menu, set the Parse value field to Conversation.SipXHeader.

  2. Set the Data type to From sample data.

  3. Define the expected X-header structure by selecting Get schema from sample JSON.

    Screenshot of the Parse value node, displaying the configuration values.

Define JSON schema for X-headers

In the Get schema from sample JSON dialog, provide the JSON structure that includes the X-header names you expect to receive. For example, if you expect headers such as X-CallID and X-AAI-Incoming in an incoming call, add them to your JSON schema.

Screenshot of a sample JSON schema dialog box.

Select Confirm to apply the schema.

Important

The Dynamics 365 Contact Center platform always normalizes X-header names to use a lowercase x- prefix, regardless of how the external system sends them. This means:

  • If the external system sends X-CallID, you must define it as x-CallID in your schema.

  • If the external system sends X-AAI-Incoming, you must define it as x-AAI-Incoming in your schema.

Even though the external system might use uppercase X-, your schema must always use lowercase x- so that the platform can correctly map and process the headers.

Example JSON for X-headers

{

"x-CallID": "",

"x-AAI-Incoming": ""  
}

Save the parsed data

  1. Create or select a variable in the Save as field (for example, IncomingSipXHeader).

    Screenshot of the Variable properties configuration for use with a SIP X-header.

  2. Set the variable's scope to Global to allow access across multiple topics in your agent.

Access X-header values in your topics

Once configured, you can access individual X-header values using dot notation, similar to the following examples:

  • Global.IncomingSipXHeader.'x-AAI-Incoming'

  • IncomingSIPXHeaders.sipXHeader.'X-CallID'

Runtime behavior

  • Copilot Studio only receives the first five X-headers sent by the external system.

  • Copilot Studio automatically populates the record with X-header values when names match the schema.

  • Missing X-headers have empty string values.

  • Schema updates are required when X-header names change, or if you want to receive extra headers.

Configure outgoing X-headers

You can pass custom data when transferring calls to external phone numbers using outgoing X-headers. Configure these headers in the Transfer conversation node.

Outgoing X-header requirements

  • Maximum count: Five X-headers per transfer.

  • Naming requirement: All X-header names can start with X- or x-, depending on the case the external system is expecting.

    Note

    In Copilot Studio, all incoming X-headers must start with lower case x-, even if the external system sending the X-header is using an upper case X-. The outgoing X-header defined in Copilot Studio can be either lower case or upper case, depending on what case the external system is expecting.

  • Name length: Up to 64 characters.

  • Value length: Up to 256 characters.

  • Transfer type: Only available for External phone number transfer.

Set up the Transfer conversation node

  1. Add a Transfer conversation node to your topic flow.

  2. Under Transfer type, select External phone number transfer and enter the transfer number. For example, +18005551212.

Configure X-headers in Transfer conversation node properties

  1. Select the More icon (…) of the node, and then select Properties.

  2. Select + Add to add X-header key-value pairs.

    Screenshot of a Transfer conversation node.

  3. Define the X-header entries. Outgoing X-header names are sent exactly as you define them in the Transfer conversation node. Choose the appropriate case based on what the receiving system expects.

    • Key Name: Must start with X- or x- (for example, X-AAI-Outgoing or X-CallID)
    • Value: Enter a static value or assign a variable

    Screenshot of the Transfer conversation properties.

Best practices

Schema design

  • Use descriptive X-header names that clearly indicate their purpose.

  • Keep the JSON schema updated when X-header requirements change.

  • Document your X-header schema for team reference and troubleshooting.

Variable management

  • Use global variables for X-header data that needs to be accessed across topics.

  • Choose meaningful variable names (for example, IncomingSIPXHeaders or CustomerXHeaders).

  • Initialize variables early in your conversation flow.

Error handling

  • Always check for X-header presence before using values in your logic.

  • Implement fallback behavior for missing or invalid X-header data.

  • Test thoroughly with various X-header scenarios.

Performance considerations

  • Parse X-headers early in your conversation flow.

  • Cache frequently used values in separate variables if needed.

  • Avoid repeated parsing of the same channel data.

Common issues with incoming X-headers

X-header values not received

  • Verify that the JSON schema matches the expected X-header names exactly.

  • Check that the Parse Value node is configured with Conversation.SipXHeader.

  • Ensure the variable is set to global scope if it's accessed from multiple topics.

  • Ensure that no more than five X-headers are expected, and the X-headers are the top five X-headers sent by the external system.

Empty or null X-header values

  • Confirm the external system is sending X-headers with the expected names.

  • Verify that the JSON schema includes all required X-header names with a lowercase x- prefix.

Common issues with outgoing X-headers

X-headers not sent during transfer

  • Verify that all X-header names start with X- or x-.

  • Ensure that Transfer type is set to External phone number transfer.

  • Ensure X-header values are properly assigned before the Transfer conversation node.

Transfer fails with X-headers

  • Confirm X-header names and values don't exceed the length limits.

  • Verify that the receiving system can handle the X-headers being sent.

  • Check for special characters that might cause parsing issues.

Schema management

Updating X-header schema

  • For receiving new X-headers, update the JSON sample in Define JSON schema for X-headers.

  • Confirm and save the updated schema.

  • Test the schema with the new X-header configuration.

  • Last updated on