Deploy agentsSIP overviewDial to the SIP endpoint

Use the X-EI SIP header

The X-EI SIP header lets you pass downstream call metadata from your SBC, PBX, or carrier into Synthflow so agents, analytics, and post-call workflows immediately inherit that context. Use it any time you need to correlate distributed call legs or identify where a transfer originated.

When to use X-EI

  • Preserve a platform-native call ID (Twilio CallSid, carrier GUID, etc.) for every leg of a transfer so custom actions can cross-reference it without re-mapping IDs.
  • Carry your own external call identifiers from PBXs or CRMs to keep reporting aligned between Synthflow and legacy systems.
  • Track diversion chains even when carriers strip the standard Diversion header—Synthflow can reconstruct it through X-EI.

Header format

X-EI expects a semicolon-delimited list of tokens. Each token begins with one of three prefixes followed by a dot and the value:

(S|E|O).([^\;]+);

You can send any subset of tokens in any order. All combinations are valid.

TokenPurposeExample
S.<call_id>Synthflow’s Call ID.S.abc123;
E.<external_id>Your own call ID from a PBX, CRM, or ticketing system so every leg of the call maps back to your records.E.crm456;
O.<diversion>Original caller or diversion history. Synthflow proxies fall back to X-Diversion if the Diversion header is stripped.O.+15551234567;
X-EI: S.abc123;E.crm456;O.+15551234567;

Avoid semicolons in the token values. Each token ends with ;, so additional semicolons break parsing.

Using the values in Synthflow

Once the INVITE reaches Synthflow, the platform maps the token values to reusable placeholders for prompts, actions, and post-call workflows:

PlaceholderSource token
<call_id>S.<call_id>
<external_id>E.<external_id>
<diversion>O.<diversion>

You can call these placeholders inside before-the-call or during-the-call custom actions without additional setup. The E. token also surfaces as call.external_id in the post-call webhook response.

Example: Passing external_id via Twilio Dial SIP

Configuration

TwiML snippet
voice.dial().sip(
  f"sip:{CURRENT_CUSTOM_NUMBER}@{CFG.termination}?X-EI=S.{synthflow_call_id};E.someExternalID;"
)

In this example, we are passing E.someExternalID inside the Dial().sip(…) URI.

Deployment notes

  • Combine any tokens you need—S + E, S + O, or all three.
  • Keep values short to avoid SIP header size limits, especially on UDP trunks.
  • If upstream carriers remove Diversion, Synthflow merges the contents of X-Diversion into the O. token automatically.
  • Ensure the header remains URL-encoded if you add it to a query string inside your SIP target URI.

Troubleshooting checklist

  • Header missing? Verify your SBC forwards custom SIP headers end-to-end.
  • Wrong external_id in webhooks? Confirm the E. token matches the format E.<your_id>; and isn’t URL-escaped twice.
  • Diversion chain incomplete? Check whether the carrier strips Diversion—Synthflow only reconstructs it if X-Diversion is present.