Send custom SIP headers on voice transfers

When a voice agent transfers a live call to an external SIP destination, you can include custom SIP headers with the transfer. The receiving system can use these headers for call routing or to carry business context, such as a queue or skill hint, campaign ID, transfer reason, or any other custom payload.

• This capability applies to the Kore Voice Gateway voice channel. - This capability is currently in Alpha. The platform builds and sends the transfer request with the configured custom headers, but header delivery depends on the gateway and receiving SIP peer. Validate the behavior in your SIP environment before using it in production.

This guide covers transfers that use the SIP REFER method.

How custom SIP headers are applied

Custom SIP headers are controlled at three levels:

Platform-supported headers
         ↓
Project-level Allowed Transfer Headers
         ↓
Agent-level header names and values
         ↓
SIP REFER transfer

A header is forwarded only when:

• Its name is supported by the platform.
• It is added to the project’s Allowed Transfer Headers list.
• A header value is configured for the transfer in the agent.

Platform-supported headers

The platform supports a default fixed set of header names for voice transfers. Supported header names are:

x-custom-data      x-session-id       x-tenant-id        x-agent-id
x-contact-id       x-project-id       x-correlation-id   x-request-id
x-queue            x-skill            x-campaign         user-to-user
x-transfer-reason

• Header names are case-insensitive and normalized to lowercase.
• To add a custom header to an agent transfer, ensure it is added to the project’s** Allowed Transfer Headers** list. You cannot add new header name directly during agent routing configuration.

Configure allowed transfer headers for the project

At the project level, select which platform-supported headers to forward during voice transfers.

• Go to Project Settings > Agent Transfer > Voice Gateway.
• Enable Header Passthrough.
• Under Allowed Transfer Headers, review the predefined SIP headers and delete any headers that are not required for agent transfers.
  • For each header, choose how its value is populated:
    • Caller-supplied (inbound): Uses the value received in the incoming SIP header.
    • Fixed value: Sends the value you specify.
    • AI chooses: Lets the AI determine the value at transfer time (supported headers only).
• In addition to the predefined SIP headers, you can add custom SIP headers that are sent during agent transfers. To add a custom header, under Add header field, enter the SIP header name (for example, x-my-header) and click Add. Configure the new header by selecting its value source and, if applicable, specifying a fixed value.
• Save the configuration.

For example, if the project allows the following, agents can use these headers in transfer configurations. Other platform-supported headers are not forwarded unless they are also added to this list.

x-queue
x-skill
x-transfer-reason

Use custom headers only when the receiving SIP system expects them. Header names must start with x- and also follow your SIP provider’s or receiving application’s requirements.

Configure SIP headers in the agent

After a header is allowed at the project level, configure its value for the agent’s transfer.

1. Open the agent in Studio > Agent Editor.
2. Open the Escalation configuration.
3. Under Routing, expand Voice Settings.
4. Set Transfer Method to SIP REFER.
5. Under SIP Headers, add the required header name and value:
   • Header name — Select or specify a header permitted by the project’s Allowed Transfer Headers configuration, for example, x-queue.
   • Header value — Specify the value to send, for example, tier2.
6. Select + Add Header to configure additional headers.
7. Save the agent.

Example:

ESCALATE:
  routing:
    connection: <your-connection>
    voice:
      transfer_method: refer
      sip_headers:
        x-queue: "tier2"
        x-transfer-reason: "billing"

In this example:

• x-queue and x-transfer-reason must be supported by the platform.
• Both headers must be added to the project’s Allowed Transfer Headers list.
• The agent supplies the values tier2 and billing for the transfer.

Troubleshooting

Symptom	Likely cause / fix
Header never arrives	Name isn’t on the platform allowlist → use an allowed name.
No custom headers at all	Header Passthrough is off → turn it on.
Only some headers arrive	They were excluded by your project Allowed Transfer Headers list, or you exceeded the 10-header limit.
Value looks cut off	Value exceeded 256 characters and was truncated.
Need a BYE-based release with headers	Not supported yet (the bye method is blocked in settings).
Want a re-INVITE instead of REFER	Choose SIP INVITE as the transfer method (requires a valid sip:/sips: target URI).