Skip to content
TriedDocs
Telephony

SIP headers

Read custom SIP headers from inbound calls as dynamic variables, send your own headers on outbound calls and transfers, and set headers on the BYE.

SIP headers carry context between your phone system and the agent: a customer ID from your PBX, the original dialled number, or a disposition code when the call ends. Tried passes headers in both directions.

Needs keys

Headers only exist on real SIP calls through LiveKit SIP. Web calls and mock mode have none.

Inbound headers#

Every number's inbound trunk passes these headers from the INVITE to the call:

  • every header whose name starts with X-
  • User-to-User
  • Diversion
  • History-Info
  • P-Asserted-Identity

Tried stores them with lower-case names in metadata.sip_headers and adds each one as a dynamic variable with the same lower-case name.

For an INVITE with these headers:

X-Customer-Id: 48213
X-Queue: billing
Diversion: <sip:+61290001234@pbx.example.com>;reason=unconditional

the call gets:

{
  "metadata": {
    "sip_headers": {
      "x-customer-id": "48213",
      "x-queue": "billing",
      "diversion": "<sip:+61290001234@pbx.example.com>;reason=unconditional"
    }
  },
  "retell_llm_dynamic_variables": {
    "x-customer-id": "48213",
    "x-queue": "billing",
    "diversion": "<sip:+61290001234@pbx.example.com>;reason=unconditional"
  }
}

Use them in the prompt as {{x-customer-id}} or {{x-queue}}. They are not part of the inbound call webhook payload; if the webhook returns a variable with the same name, the webhook value wins. The agent's pre-call workflow receives them with the other variables.

Other headers (for example Identity) are not added to the call, but Tried reads Identity, P-Attestation-Indicator, X-Telnyx-CNAM and P-Asserted-Identity for caller trust.

Outbound headers#

Send headers on the INVITE of an outbound call with custom_sip_headers on POST /v2/create-phone-call:

{
  "from_number": "+61255501234",
  "to_number": "+61412345678",
  "retell_llm_dynamic_variables": { "ticket": "T-1009" },
  "custom_sip_headers": {
    "X-Ticket": "{{ticket}}",
    "X-Source": "tried"
  }
}
  • Values may contain {{variables}}, rendered with the call's dynamic variables.
  • Header names must be valid SIP tokens: letters, digits and the symbols allowed in a SIP token, with no spaces or colons. An invalid name returns 400.
  • Line breaks in values are replaced with spaces.
  • The headers are stored on the call as custom_sip_headers.

Transfer headers#

Transfer tools can set custom_sip_headers too. They are sent on the transfer INVITE or on the REFER, so the person or queue receiving the transfer gets the context.

Headers on the BYE#

An end_call tool, or an end node in a conversation flow, can set custom_sip_headers that are sent on the BYE when the agent hangs up. Use them to tell your PBX how the call ended. Only these header names are sent on the BYE by default:

  • X-Disposition
  • X-Call-Outcome
  • X-Transfer-Reason
  • X-Tried-Call-Id

Change the list with BYE_HEADER_NAMES (comma separated) on the API, then re-provision numbers with POST /provision-phone-number/:n so their trunks map the new names.

Header-based routing patterns#

Goal How
Personalise the greeting from a CRM ID PBX sets X-Customer-Id; the agent's pre-call workflow or the inbound webhook looks it up and returns variables
Know which IVR option the caller chose PBX sets X-Queue; the prompt branches on {{x-queue}}
Pass context from Amazon Connect User-to-User arrives as {{user-to-user}}
Report the outcome to the PBX end_call tool with X-Disposition