SIP headers on SIP trunk calls

SIP headers carry information alongside a call. On a SIP trunk you can read two carrier headers on inbound calls, and send headers of your own on outbound calls and on transfers.

Direction	What you can do	Where it is set
Inbound	Read `P-Asserted-Identity` and `Diversion` into prompt variables	Agent, `sip_header_variables`
Outbound	Send your own headers on every call the agent places	Agent, `sip_headers`
Transfer	Send your own headers on the call to the transfer target	Transfer tool, `sip_headers`

Inbound header variables

Bolna passes two headers from your carrier’s INVITE to the agent: P-Asserted-Identity and Diversion. Other headers on the INVITE do not reach the agent. To use either one, map it to a variable name on the agent; the variable then appears in recipient_data and in the prompt as {variable_name}. The variable holds the header’s value exactly as your carrier sent it, display name and parameters included, for example "Asha" <sip:+919876543210@203.0.113.10>. If the INVITE carries the same header more than once, the first one is used. A header that is not on a call leaves its variable empty; the call still goes ahead.

Open the agent's inbound settings

Open the agent, go to the Calling tab and set Telephony Provider to SIP Trunk. The SIP Header Variables section appears under Inbound Calling.

Map the headers

Click Add header. Enter the header name on the left, exactly P-Asserted-Identity or Diversion, and the variable name on the right, for example caller_identity. Header names are case-sensitive. Any other header name shows a warning, because a SIP trunk never passes it to the agent.

Agent Calling tab, SIP Header Variables section under Inbound Calling, with P-Asserted-Identity mapped to caller_identity and Diversion mapped to diverted_from — Mapping P-Asserted-Identity to a variable

Use the variable

Reference it in the prompt or welcome message, for example The network reports the caller as {caller_identity}.

The Ingest lookup key below the mappings can pick one of these headers to look the caller up in your caller data instead of from_number. The lookup uses the header’s full value, so your data source has to store it in the same form.

Outbound header templates

Headers you set on the agent go on every INVITE the agent places through a trunk: single calls, batches and workflow calls. Each value is a template, and %(name)s in it is replaced with that call’s variable, typically from the user_data you pass when placing the call.

{
  "X-Account-Id": "%(account_id)s",
  "X-Campaign": "renewals-q4"
}

A call with "user_data": {"account_id": "48219"} sends X-Account-Id: 48219 and X-Campaign: renewals-q4. A header whose value comes out empty, because the call has no such variable, is left off that call.

Open the agent's tools

Save the agent with Telephony Provider set to SIP Trunk, then open its Tools tab. SIP headers on outbound calls is at the bottom of the Function Tools for LLM Models card.

Add headers

Click Add header, enter the name and the value, and click Save headers.

Agent Tools tab, SIP headers on outbound calls section, with an X-Account-Id header whose value is %(account_id)s, and Add header and Save headers buttons — Outbound SIP headers on the Tools tab

A call uses the headers saved on the agent version it runs on.

Header rules

These apply to outbound and transfer headers on SIP trunk agents. Bolna refuses to save a header whose name or template breaks them. A value that breaks them only once a variable is filled in, for example by running past 120 characters, is left off that call.

Rule	Detail
Name	Letters, digits and dashes, up to 64 characters. Each name once, ignoring case.
Value	Up to 120 characters after substitution. No quotes, pipes, curly braces, backslashes or control characters.
Reserved for Bolna	Any name starting with `X-Bolna-`, plus `X-Client-Call-Id` and `X-Trunk`
Owned by SIP	`Via`, `From`, `To`, `Call-ID`, `CSeq`, `Contact`, `Route`, `Record-Route`, `Max-Forwards`, `Content-Length`, `Content-Type`, `Authorization`, `Proxy-Authorization`, `P-Asserted-Identity`, `P-Preferred-Identity`, `Remote-Party-ID`, `Privacy`, `Diversion`, `History-Info`, `Refer-To`, `Referred-By`, `Replaces`, `Require`, `Proxy-Require`, `Supported`, `Allow`, `Session-Expires`, `Min-SE`, `Expires`, `Event`

Headers Bolna adds

Every outbound and transfer INVITE on a trunk also carries two headers of Bolna’s own, which you can use to match your carrier’s records to Bolna’s:

Header	Value
`X-CLIENT-CALL-ID`	The Bolna execution ID of the call
`X-TRUNK`	The trunk ID

Transfer-leg headers

When an agent on a SIP trunk transfers a call, the call to the transfer target carries the headers set on that transfer tool, not the agent’s outbound headers. Values use the same %(name)s templates and the same rules. On an inbound call, the variables include your mapped header variables and any caller data, so you can forward what the carrier told you about the caller. In the dashboard, the Transfer Call tool shows Custom SIP headers when the destination is SIP trunk (URI). Through the API, a transfer tool’s sip_headers apply whichever destination type it uses.

Using the API

Set both agent-level fields with the agent PATCH endpoint. Send null to clear either one.

curl -X PATCH https://api.bolna.ai/v2/agent/<agent_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_config": {
      "sip_header_variables": {
        "P-Asserted-Identity": "caller_identity",
        "Diversion": "diverted_from"
      }
    }
  }'

curl -X PATCH https://api.bolna.ai/v2/agent/<agent_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_config": {
      "sip_headers": {
        "X-Account-Id": "%(account_id)s",
        "X-Campaign": "renewals-q4"
      }
    }
  }'

A header that breaks a rule is refused with 400, for example reserved header X-Trunk. A transfer tool carries its headers in its param, next to the destination:

{
  "call_transfer_number": "+918045670000",
  "sip_headers": {
    "X-Caller-Identity": "%(caller_identity)s"
  }
}

See Transfer calls for the rest of the transfer tool.

Build

Deploy

Monitor

Go live

SIP headers on SIP trunk calls

Inbound header variables

Outbound header templates

Header rules

Headers Bolna adds

Transfer-leg headers

Using the API

​Inbound header variables

​Outbound header templates

​Header rules

​Headers Bolna adds

​Transfer-leg headers

​Using the API

Inbound header variables

Outbound header templates

Header rules

Headers Bolna adds

Transfer-leg headers

Using the API