***

title: 'Use SIP X-Headers in Prompts, Actions & Transfers'
subtitle: >-
Pass custom metadata from your SIP infrastructure into Synthflow and reference
it anywhere.
slug: sip-x-headers-in-prompts
description: >-
Learn how to use custom SIP X-\* headers in Synthflow prompts, custom actions,
and transfer headers for dynamic, context-aware voice AI agents.
----------------------------------------------------------------

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

1. Your SBC or PBX adds one or more `X-*` headers to the SIP INVITE sent to Synthflow.
2. Synthflow extracts each header and maps it to a variable using the header name (with the `X-` prefix).
3. 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.

```json
{
  "account_id": "{X-Account-ID}",
  "language": "{X-Language}"
}
```

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.

```json
{
  "caller_name": "{X-Customer-Name}",
  "priority": "{X-Priority}",
  "call_id": "{call_id}"
}
```

<Note>
  You can combine X-header variables with [system variables](/use-action-variables-in-inbound-sip-calls) like `{call_id}`, `{from_phone_number}`, and variables returned by other actions (`{results.data.field}`).
</Note>

***

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

<Tip>
  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.
</Tip>

***

## 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-insensitive per SIP spec, but use consistent casing for readability                 |

<Warning>
  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.
</Warning>

***

## 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
                  └──────────┘
```

***

## Related Links

* [SIP Transfers — Custom X-Headers](/call-transfer-to-sip#custom-x-headers)
* [Use the X-EI SIP Header](/x-ei-sip-header)
* [Forward Calls Using SIP Diversion Headers](/diversion-headers)
* [Use Action Variables in Inbound SIP Calls](/use-action-variables-in-inbound-sip-calls)