SIP headers and call data
Which SIP headers arrive with a call, how flows and bots read them, how the edge rewrites them and which headers the application can send when it ends or transfers a call. Browse the feature map or configuration finder.
Availability: Next. Entries that depend on an optional feature, a role or a deployment choice name it in their own Availability line.
Features in this family
- Inbound SIP headers available to the call
- Read a SIP header in a flow
- SIP header manipulation rules at the edge
- Dynamic values in header rules
- Assign header rule sets to a base number
- Send SIP headers on hangup and transfer
- SIP header name validation
- Transfer reason on the new call leg
- Custom headers passed to carriers
- Reserved and internal SIP headers
- Optional SIP header budget
- Per-trunk BYE size budget
- Trace headers on SIP messages
- Carrier REFER normalization
Inbound SIP headers available to the call
Every header of the incoming INVITE is captured and kept with the call, so flows can read it; a bot receives only the non-internal headers its forwarding rules select.
For: Integrators, Application builders
| Level | Where to change it | Owner section |
|---|---|---|
| Flow and node settings | Flow variables › sipHeaders (read-only, telephony)(sipHeaders) | Find and declare flow variables |
Read more:
- Reference: Find and declare flow variables
- How it works: Routing, causes, and diagnostic headers
Related features: Read a SIP header in a flow, Reserved and internal SIP headers.
Read a SIP header in a flow
A flow reads a caller header from the read-only sipHeaders object, for example in a condition or a webhook body, without any edge rule.
For: Application builders
| Level | Where to change it | Owner section |
|---|---|---|
| Flow and node settings | Variable field picker › sipHeaders(sipHeaders) | Insert a variable into a field |
Read more:
- Reference: Find and declare flow variables
- Set it up: Insert a variable into a field
Related features: Inbound SIP headers available to the call.
SIP header manipulation rules at the edge
Named rule sets add, remove, modify or copy headers on incoming or outgoing SIP messages, in priority order and optionally only for a trunk, source address or number pattern.
For: Team administrators, Deployment operators
| Level | Where to change it | Owner section |
|---|---|---|
| Platform settings | Telephony › Header Manipulation(HeaderManipulationConfig, HeaderManipulationRule, direction, action, priority, sourceHeader, conditions) | 1. Create or open the correct configuration |
Read more:
- Set it up: 1. Create or open the correct configuration
- Reference: 2. Set the rule fields
- Reference: 3. Restrict matching and understand order
- Troubleshoot: 4. Verify persistence, assignment and activation
Related features: Dynamic values in header rules, Assign header rule sets to a base number, Optional SIP header budget.
Dynamic values in header rules
A rule value can contain placeholders such as caller user, called number, call ID, trunk or original headers, which the edge fills in for each message.
For: Team administrators, Deployment operators
| Level | Where to change it | Owner section |
|---|---|---|
| Platform settings | Header rule › Value(__SOURCE_VALUE__, __FROM_USER__, __TO_USER__, __CALL_ID__, __CALLED_NUMBER__, __TRUNK_ID__, __ORIGINAL_FROM__, __P_ASSERTED_IDENTITY__) | Value substitutions |
Read more:
- Reference: Value substitutions
Related features: SIP header manipulation rules at the edge.
Assign header rule sets to a base number
A team administrator attaches additional header rule sets to a number already assigned to the team, while the default sets stay in place.
For: Team administrators
| Level | Where to change it | Owner section |
|---|---|---|
| Team settings | Manage Team › Base numbers › Header Manipulation Configs(headerManipulationConfigIds) | Change a base-number header assignment separately |
Read more:
Related features: SIP header manipulation rules at the edge, Extensions on a base number.
Send SIP headers on hangup and transfer
A flow can attach custom headers to the BYE that ends a call or to a transfer request, within the platform header budget.
For: Integrators, Application builders
| Level | Where to change it | Owner section |
|---|---|---|
| Flow and node settings | End node and transfer action › SIP headers(sipHeaders, hangupSipHeaders, transferSipHeaders, transferSipQueryParams) | Diagnostic header formats |
Read more:
- Reference: Diagnostic header formats
- Reference: 4. Add SIP headers
- Reference: If optional termination headers are invalid
Related features: Optional SIP header budget, Headers and URI parameters on a transfer, Hang up from a flow or a bot, SIP header name validation.
SIP header name validation
Configured SIP header names must use the supported characters. Invalid names are rejected when you save.
For: Integrators
Read more:
- Reference: Proxy-compatible header names
- Troubleshoot: If optional termination headers are invalid
Related features: Send SIP headers on hangup and transfer.
Transfer reason on the new call leg
A transfer INVITE carries an X-Transfer-Reason header with the cause, the SIP code and the Q.850 value, instead of a copied Reason header.
For: Integrators
Read more:
- Reference: Cause values and SIP responses are different
Related features: Platform termination causes and SIP mapping, Send SIP headers on hangup and transfer.
Custom headers passed to carriers
Toward a carrier trunk the edge removes custom X- headers except a fixed set of customer, queue, original-number, transfer and agent headers.
For: Integrators
Read more:
- Reference: Protected headers and normalization
Related features: Send SIP headers on hangup and transfer, Reserved and internal SIP headers.
Reserved and internal SIP headers
Platform routing and trace headers and every X-Delphi header are reserved and cannot be set by the application.
For: Integrators
Read more:
- Reference: Protected headers and normalization
Related features: Optional SIP header budget, Custom headers passed to carriers.
Optional SIP header budget
Custom headers share a fixed budget for count, name length, line length and total size so that the final message stays within what common gateways accept.
For: Integrators, Application builders
Read more:
- Reference: Default optional-header limits
- Troubleshoot: 5. Choose a method and outcome mode
Related features: Per-trunk BYE size budget, Send SIP headers on hangup and transfer, Reserved and internal SIP headers.
Per-trunk BYE size budget
A trunk can cap the size of the BYE it receives; optional headers are dropped first when the cap is reached, while protected headers stay.
For: Deployment operators, Team administrators
| Level | Where to change it | Owner section |
|---|---|---|
| Platform settings | SIP trunk and egress trunk › BYE size budget(sipByeMaxBytes, sipByeOverheadBytes) | Routing and technical fields |
Read more:
- Reference: Routing and technical fields
- Reference: Default optional-header limits
Related features: Optional SIP header budget.
Trace headers on SIP messages
The edge adds trace, span and transaction headers to calls so voice logs and SIP traces of one call can be joined.
For: Deployment operators
Read more:
- Reference: Correlation
- Troubleshoot: 3. Inspect the corresponding SIP message
Related features: Reserved and internal SIP headers.
Carrier REFER normalization
For REFER requests from a carrier such as Twilio, the edge rewrites Contact, Refer-To and Referred-By so the transfer reaches the platform and not a loopback address.
For: Integrators, Deployment operators
Read more:
- Reference: Call transfer methods
Related features: Transfer methods (REFER, INVITE, BYE), REFER target host.