Trunk Custom Headers
The SIP standard leaves room for interpretation for many headers, especially when it comes to connecting to the public switched telephony network (PSTN). The PBX can send just about anything in the SIP headers when making outbound calls. This is particularly useful if the trunk provider needs special parameters/values in the SIP headers.
In order to use custom headers, "Custom Headers" must be selected from the SIP caller-ID presentation drop-down (trunk setting).
The system generally supports seveal presentation of phone numbers.
- The global presentation of numbers starts with the
+-sign, followed by the country code and the domestic number. This presentation is the most unambiguous way of presenting a phone number and is used internally by the PBX when passing phone numbers around. It is also used by many service providers, especially those that cover several countries. - The E.164 format is similar, but omits the
+-sign. - The North American Number Presentation Association (NANPA) format removes the
+1from domestic numbers and uses011instead of the+sign. The 11-digit format uses the E.164 format for domestic numbers. - The rest of world (ROW) format uses
00to replace the+-sign and uses a single0as prefix for domestic numbers.
The list of trunk variables is long. When you select log level 9 for trunk, the log will contain all variables with their value. This makes it easier to pick the right variable when setting up custom headers.
The predefined tags are detailed below:
| Template/Tag | Meaning | Example Result |
|---|---|---|
{open} | This is a special tag for { | { |
{close} | This is a special tag for } | } |
{replacement} | Result of dial plan replacement | sip:18005554600@vodia.com;user=phone |
{global-uri-number} | The replacement number in global form | +18005554600 |
{local-uri-number} | The replacement number in the trunk country code format | 8005554600 |
{request-uri} | The replacement number in the trunk country code format inserted into the dial plan replacement | sip:8005554600@vodia.com;user=phone |
{domain} | The tenant DNS address. | pbx.company.com |
{domain-display} | The name of the tenant | Vodia Networks |
{domain-param1-3} | Insert a general purpose parameter for the tenant. | Anything |
{dom-ani} | The value of the ANI field for the tenant | +16173998147 |
{dom-ani-e164} | The {dom-ani} in E.164 format | 16173998147 |
{dom-ani-nanpa} | The {dom-ani} in NANPA format | 16173998147 |
{dom-ani-plus} | The {dom-ani} in global format | +16173998147 |
{dom-ani-row} | The {dom-ani} in rest-of-world format | 0016173998147 |
{ani-raw} | The ANI from the Trunk ANI process | 6173998147 |
{ani} | The ANI in the trunk format | 6173998147 |
{ani-e164} | The ANI in E.164 format | 16173998147 |
{ani-nanpa} | The ANI in NANPA format | 6173998147 |
{ani-plus} | The ANI in global format | +16173998147 |
{ani-row} | The ANI in ROW format | 0016173998147 |
{ani-cnam} | The CNAM from the Trunk ANI process | Jim Test |
{ext-user} | The primary account name for the user that is associated with the call. If there is no user associated with the call, the username part of the other call leg is used. | 42 |
{ext-uri} | The {ext-user} presented as URI for the tenant | sip:42@vodia.com |
{ext-display} | The name for the user | Jim Test |
{ext-param1-3} | The parameter 1-3 for the user. If there is no account context available or the content for the account is empty, it will take the general purpose parameters of the tenant. | Anything |
{ext-epid} | The endpoint ID for the user | 7346209648 |
{ext} | The {ext-display} and the {ext-uri} combined | "Jim Test" <sip:42@vodia.com> |
{ext-ani} | The ANI resolved for the extension via the Trunk ANI process. Falls back to {dom-ani} if no ANI is configured for the extension. | 6173998147 |
{ext-ani-raw} | The {ext-ani} before format conversion | 6173998147 |
{ext-ani-e164} | The {ext-ani} in E.164 format | 16173998147 |
{ext-ani-nanpa} | The {ext-ani} in NANPA format | 6173998147 |
{ext-ani-plus} | The {ext-ani} in global format | +16173998147 |
{ext-ani-row} | The {ext-ani} in rest-of-world format | 0016173998147 |
{ext-ani-cnam} | The CNAM associated with the {ext-ani} | Jim Test |
{trunk-account} | Value of the account field of the trunk | 8005559999 |
{trunk-password} | Value of the password field of the trunk (the actual value is not shown in the log) | password |
{trunk-display} | Value of the display field of the trunk. | Vodia Networks |
{trunk-user} | The username setting of the trunk | 8005559999 |
{trunk-uuid} | The UUID for the trunk. | 9f97bb42-22c8-4d8c-8b10-000413453704 |
{trunk-registrar} | Value of trunk registrar setting | vodia.com:5060 |
{trunk-host} | Host part of the trunk registrar | vodia.com |
{trunk-port} | Port part of the trunk registrar. | 5060 |
{trunk-outbound-proxy} | Outbound proxy setting of the trunk | sip:10.20.14.116:5060;transport=udp |
{trunk-ani} | Value of the ANI field of the trunk. | 8005559999 |
{trunk-uri} | The user and registrar combined | 8005559999@vodia.com |
{trunk} | The URI and the display value combined | "Vodia Networks" <sip:8005559999@vodia.com:5060> |
{icid-value} | Trunk charging vector setting | 2424324 |
{ip-address} | IP address of the system | 10.20.10.100 |
{from-trunk} | This variable is true when the call originates from a trunk (trunk to trunk call); otherwise it is false | true |
{from-extension} | This variable is true when the call originates from an extension; otherwise it is false | true |
{disa} | This variable is true when the call is a DISA call (a user placing an outbound call from the cell phone menu); otherwise it is false | true |
{clip} | This variable is true when the caller-ID should be hidden, either by request from the user or because it came in anonymous from a trunk; otherwise it is false | true |
{emergency} | This variable is true when the an emergency number is being called; otherwise it is false | true |
{fax} | This variable is true when the call is a fax call; otherwise it is false | false |
{anonymous} | The literal string Anonymous, for use in constructing anonymous caller-ID headers | Anonymous |
{from-clip} | The From header value as presented to the called party, respecting CLIP (caller-ID hiding) rules | "0272010788" <sip:0272010788@pbx.company.com;user=phone> |
{orig-ioi} | The originating IOI (IMS charging identifier) from the incoming call | pbx.company.com |
{privacy-id} | The privacy ID value for the call | `` |
{version} | The PBX software version | 69.5.21 |
{in-reply-to} | This variable contains the call-ID of the original call | 325s92318d2@192.168.4.2 |
{from-*} * | The value of the From-header | "Vodia Networks" <sip:8005559999@vodia.com> |
{to-*} * | The value of the To-header | "Vodia Networks" <sip:8005559999@vodia.com> |
{pai-*} * | The P-Asserted-Identity header from the primary call. | "Vodia Networks" <sip:8005559999@vodia.com> |
{ppi-*} * | The P-Preferred-Identity header from the primary call. | "Vodia Networks" <sip:8005559999@vodia.com> |
{rpi-*} * | The Remote-Party-ID header from the primary call. | "Vodia Networks" <sip:8005559999@vodia.com> |
{from} | The {ani-cnam} and {ani} combined | "Vodia Networks" <sip:8005559999@vodia.com> |
{location} | This variable is true when a location is available; otherwise it is false | true |
{location-name} | The name of the location | Headquarter |
{location-comment} | The comment for the location | The one in Boston |
{location-street} | The street of the location | 33 Broad St |
{location-apartment} | The additional information for the location | Suite 3002 |
{location-city} | The city of the location | Boston |
{location-state} | The state of the location | MA |
{location-zip} | The ZIP-code for the location | 02109 |
{location-country} | The country of the location | USA |
{location-latitude} | The latitude of the location | 32.43534 |
{location-longitude} | The longitude of the location | -32.324325 |
{location-url} | The URL for the location | https://vodia.com/location |
{location-geo} | The URL for the location in header format | <https://vodia.com/location> |
{if var value} | If var is not equal to the shown value, the rendering stops | {if clip true} |
{fi var value} | If var is not equal to the shown value, the rendering continues | {fi clip true} |
{ifn var value} | If var is equal to the shown value, the rendering stops | {ifn clip true} |
{fin var value} | If var is equal to the shown value, the rendering continues | {fin clip true} |
The P-Asserted-Identity, P-Preferred-IdentityandRemote-Party-ID` headers are taken from the primary call leg of the call. Because the PBX has no control over those headers, care should be taken when relying on the value of those headers.
Caller-ID fields
For the fields {from}, {to}, {ppi}, {pai} and {rpi} the system generates the following content (xx will be replaced with the actual field name):
| Template/Tag | Meaning | Example Result |
|---|---|---|
{xx-noclip} | The complete header for the call, even if CLIP is used for the call | "Vodia Networks" <sip:8005554600@vodia.com> |
{xx-uri} | Only the URI part of the header | sip:8005554600@pbx.company.com;user=phone |
{xx-display} | The display name of the calling extension | Vodia Networks |
{xx-host} | The host part of the URI | pbx.company.com |
{xx-port} | The port part of the URI | 5060 |
{xx-hostport} | The host and port part of the URI | pbx.company.com:5060 |
{xx-scheme} | The scheme part of the URI | sip |
{xx-uri-raw} | To URI before formatting | sip:+18005554600@pbx.company.com;user=phone |
{xx-user} | User part of To URI | 8005554600 |
{xx-user-raw} | User part of To URI before formatting | +18005554600 |
Complex Header Expressions
The conditional tags {if}, {fi}, {ifn}, and {fin} can be combined with other variables to build headers whose content varies based on call context — for example, presenting different ANI values depending on whether the call originates from an extension or arrives from a trunk.
Available Conditions:
- from-trunk: If the call comes from a trunk, this condition will be
true. - from-cell: When the call comes from a users cell phone, this condition is
true. - from-teams: When the call comes from a users Teams phone through the Teams trunk, this condition is
true(available from version 65.0.5 onwards). - from-ext: When the call comes from a users extension, this condition is
true. - hunt: This condition will be
trueif this call is a hunt group call (starting version 62.1). - acd: This condition will be
trueif this call is a agent group call (starting version 62.1). - clip: If the call should block the caller id (CLIP) then this condition will be
true. - disa: This condition will be
trueif this call is a DISA (direct inbound station access) call. - fax: This condition will be
trueif this call is a FAX call.
The general pattern for an if/else block is:
{if var value}<content when var equals value>{fi var value}{ifn var value}<content when var does not equal value>{fin var value}
The {if} tag stops rendering if the variable does not match the value; {fi} resumes rendering. Conversely, {ifn} stops rendering if the variable does match; {fin} resumes. Pairing them back-to-back produces a clean if/else.
Example 1: Use extension ROW ANI for outbound calls, pass through inbound From header otherwise
{if from-extension true}{ext-ani-row}@{from-host}{fi from-extension true}{ifn from-extension true}{from-noclip}{fin from-extension true}
When {from-extension} is true (the call comes from an extension), this renders the extension's ANI in rest-of-world format combined with the From host — for example 0016173998147@pbx.company.com. When the call comes from a trunk, it renders the full incoming From header verbatim (respecting CLIP), passing the original caller-ID through unchanged.
Example 2: Use extension ANI for outbound, pass through PAI URI otherwise
{if from-extension true}{ext-ani}@{from-host}{fi from-extension true}{ifn from-extension true}{pai-uri-raw}{fin from-extension true}
Similar to Example 1, but uses {ext-ani} (the resolved extension ANI in trunk format, falling back to the domain ANI if none is set for the extension) rather than the ROW-formatted variant. For inbound/trunk-originated calls, it forwards the raw PAI URI directly instead of the From header. This is useful when the carrier expects the PAI URI to be echoed back on re-invite scenarios.