Use SIP X-Headers in Prompts, Actions & Transfers

Synthflow now accepts arbitrary X-* SIP headers on inbound calls. Any custom header your SBC, PBX, or carrier attaches to the SIP INVITE is automatically extracted and made available as a variable throughout the call lifecycle — in prompts, before-the-call and during-the-call custom actions, and outbound transfer headers.

This means you can inject caller context, routing metadata, or business-specific data directly from your telephony infrastructure without building separate API integrations.

How It Works

Your SBC or PBX adds one or more X-* headers to the SIP INVITE sent to Synthflow.
Synthflow extracts each header and maps it to a variable using the header name (with the X- prefix).
You reference those variables in prompts, custom actions, and transfer X-headers using {X-header-name} syntax.

INVITE sip:+12065551234@sip.synthflow.ai SIP/2.0
X-Customer-Name: Jane Doe
X-Account-ID: ACC-98765
X-Language: es
X-Priority: high

In this example, Synthflow extracts four variables you can use anywhere in the agent configuration.

Referencing X-Header Values

Use the header name as a variable wherever Synthflow supports dynamic values. The X- prefix is included in the variable name.

Where	Syntax	Example
Agent prompt	`{X-Header-Name}`	`The caller's name is {X-Customer-Name} and their preferred language is {X-Language}.`
Before-the-call action	`{X-Header-Name}` in the request body	`{"account_id": "{X-Account-ID}"}`
During-the-call action	`{X-Header-Name}` in the request body	`{"priority": "{X-Priority}"}`
Transfer X-headers	`{X-Header-Name}` as the header value	Header `X-Account-ID` with value `{X-Account-ID}`

Use in Prompts

Reference any incoming X-header directly in your agent’s prompt to personalize the conversation from the first word.

Example prompt:

You are a support agent for Acme Corp.
The caller's name is {X-Customer-Name} and their account ID is {X-Account-ID}.
Their preferred language is {X-Language}.
This call has {X-Priority} priority — if priority is "high", escalate unresolved issues immediately.

The values are resolved before the first agent turn, so the AI has full context from the start of the call.

Use in Custom Actions

Before-the-call actions

Pass X-header values in the request body of a pre-call action to enrich the call context from an external system.

1 {
2   "account_id": "{X-Account-ID}",
3   "language": "{X-Language}"
4 }

Your API can use these values to look up customer records and return additional variables for the prompt.

During-the-call actions

Reference X-header values in actions triggered mid-call — for example, to pass metadata to a CRM or ticketing system.

1 {
2   "caller_name": "{X-Customer-Name}",
3   "priority": "{X-Priority}",
4   "call_id": "{call_id}"
5 }

You can combine X-header variables with system variables like {call_id}, {from_phone_number}, and variables returned by other actions ({results.data.field}).

Use in Transfer Headers

When transferring a call to a SIP endpoint, you can forward incoming X-header values as outbound X-headers. This passes the original caller context through to the next leg of the call.

In Agents → Actions → Call Transfer → Custom X-Headers, add headers that reference the inbound values:

Name	Value
`X-Account-ID`	`{X-Account-ID}`
`X-Customer-Name`	`{X-Customer-Name}`
`X-Priority`	`{X-Priority}`

This ensures the receiving PBX or agent inherits the same metadata that was available to Synthflow.

You can also transform values — for example, set a new header X-Handled-By with a static value like synthflow-ai alongside the forwarded headers.

Header Naming Rules

Custom X-headers must follow standard SIP header conventions:

Rule	Detail
Prefix	Must start with `X-`
Characters	Letters (A-Z, a-z), digits (0-9), hyphen (`-`), and underscore (`_`) only. Pattern: `^X-[A-Za-z0-9\-_]+$`
Value restrictions	No CR (`\r`), LF (`\n`), or NULL (`\0`) characters
Case	Header names are case-sensitive — the variable name must match exactly how the header was sent

Headers are case-sensitive. If your SBC sends x-customer-name (lowercase), you must reference it as {x-customer-name} in prompts and actions — not {X-Customer-Name}. A mismatch in casing will result in an empty value. Always verify the exact casing your SIP infrastructure uses.

Keep custom headers minimal. Each header increases the SIP INVITE packet size. Excessive headers can cause UDP packet fragmentation and delivery failures — especially on trunks with smaller MTU settings.

Example: End-to-End Flow

                  ┌──────────┐
                  │  Your    │   X-Customer-Name: Jane Doe
  Caller ──────► │  SBC/PBX │   X-Account-ID: ACC-98765
                  │          │   X-Language: es
                  └────┬─────┘
                       │ SIP INVITE with X-* headers
                       ▼
                  ┌──────────┐
                  │Synthflow │   Extracts headers → variables
                  │  Agent   │   Uses {X-Customer-Name} in prompt
                  │          │   Passes {X-Account-ID} to actions
                  └────┬─────┘
                       │ SIP INVITE (transfer) with X-* headers
                       ▼
                  ┌──────────┐
                  │ Target   │   Receives X-Account-ID: ACC-98765
                  │ Endpoint │   Receives X-Customer-Name: Jane Doe
                  └──────────┘