***

title: Forward calls using SIP diversion headers
slug: diversion-headers
description: Use SIP Diversion headers to pass richer routing and transfer context into Synthflow for inbound calls.
---------------------

For a complete page index, fetch https://docs.synthflow.ai/llms.txt. For full documentation content, fetch https://docs.synthflow.ai/llms-full.txt.

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.

<Note>
  Diversion headers can only be passed for inbound calls.
</Note>

## 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

| Problem                                              | How Diversion Headers Help                                                                 |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Anonymous transfer chains destroy caller context     | Carries the full redirect history so your assistant still knows who the original caller is |
| Multi‑brand call centres need brand‑aware assistants | Encode 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.

<Tip>
  `<diversion>`

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

<Steps>
  <Step>
    ## 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:

    ```curl
     {
      "diversion_header": "<diversion>",
      "brand": "AcmeBank",
      "journey_stage": "loan‑apps"
    }
    ```

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

    2. SBC Adds Diversion Header
       Example INVITE after your middleware responds:
       INVITE sip:[+12065551234@voice.example.com](mailto:+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

    <Note>
      Every key (`brand`, `journey_stage`, etc.) mirrors the variable names in your prompt/template.
    </Note>
  </Step>

  <Step>
    ## 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
  </Step>
</Steps>

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.