Calls and telephonySIP overviewDial to the SIP endpoint

Forward calls using SIP diversion headers

This guide shows you how to add and modify Diversion headers before the call hits your Voice AI stack and during an active session, so you can feed richer context into prompts and actions without breaking SIP etiquette.

Diversion headers can only be passed for inbound calls.

Diversion vs SIP Headers

SIP headers:

  • Definition: Standard headers used in SIP messages to convey information like the sender, recipient, call ID, and the request type (INVITE, ACK, etc.).
  • Purpose: To establish and manage the call session.
  • Examples: “From,” “To,” “Contact,” “Call-ID,” “Via,” “Content-Type”.

Diversion headers:

  • Definition: A SIP header added to indicate a call has been redirected from another destination.
  • Purpose: To provide information about the original destination and reason for the call diversion.
  • Usage: Used in call forwarding, call transfer, and other redirection scenarios.

Why Diversion Headers Matter

ProblemHow Diversion Headers Help
Anonymous transfer chains destroy caller contextCarries the full redirect history so your assistant still knows who the original caller is
Multi‑brand call centres need brand‑aware assistantsEncode brand IDs in a standard SIP header and switch personas on the fly

General Flow

  1. Inbound Call → SIP receives INVITE.

  2. Diversion Header Injected (Pre‑Call) by SIP, CRM webhook, or lambda function.

  3. Assistant Selection based on Diversion metadata.

  4. Re‑INVITE / UPDATE (Mid‑Call) optionally tweaks Diversion to reflect new context (e.g. agent transfer, escalation).

  5. Voice AI consumes the latest Diversion value at each turn; variables automatically update inside prompts.

<diversion> is the special variable you can call into a before the call or during the call action.
1

Step 1 – Inject Diversion Header Before the Call Starts

  1. Create a Pre‑Call Action

Use an API‑based action that your SBC or middleware hits before its forwards the INVITE to the assistant.

Method: POST Trigger flag: run_action_before_call_start = true

Request body must include:

1 {
2  "diversion_header": "<diversion>",
3  "brand": "AcmeBank",
4  "journey_stage": "loan‑apps"
5}

Return: a JSON object whose keys match your prompt variables.

  1. SBC Adds Diversion Header Example INVITE after your middleware responds: INVITE sip:+12065551234@voice.example.com SIP/2.0 Via: SIP/2.0/UDP 203.0.113.5;branch=z9hG4bK‑876543 From: <sip:+14155550199@caller.net>;tag=9fxced76sl To: <sip:+12065551234@voice.example.com> X-Diversion: <sip:+15559876543@acmebank>;reason=unconditional;privacy=off;brand=AcmeBank;journey_stage=loan‑apps Contact: <sip:+12065551234@203.0.113.5> Content‑Length: 0

Every key (brand, journey_stage, etc.) mirrors the variable names in your prompt/template.

2

Step 2 – Update Diversion Header During the Call

In the same manner, for during the call custom action you can pass the <diversion> variable using this variable in the parameter

Best Practices & Gotchas Don’t rename keys casually. If you change customer_tier to loyalty, update the header and every prompt variable.

Stick to alphanumerics in sub‑parameter names; some SBCs choke on funky characters.

Size matters. Keep the header under ~1 KB or risk fragmentation on UDP.

Chain of custody. When another platform adds its own Diversion, keep yours last so you always know which index to read.

Security. Encrypt sensitive tags (e.g. account IDs) or push them via secure SIP‑TLS trunks.

Benefits Recap

  • Zero code changes in prompts when context shifts—headers drive the logic.
  • Instant persona switching for multi‑brand deployments.
  • Full audit trail: Diversion chain logs every transfer for compliance.
  • Future‑proof: ready for RCS/5G networks where Diversion gets mapped to rich call data.