The configuration template is a text file which will be served to the phone when it requests its configuration. The template can contain a set of keywords that will be replaced with the actual value of the phone the SIP phone model template is used for.
A keyword is declared as %KEYWORD-NAME%. The name is case sensitive: write it exactly as in the tables below (%Mac%, not %mac%). A keyword that is misspelled, or that the brand of the phone does not fill in, is left in the file as it is.
The variables are as follows:
| Keyword name | Usage |
|---|---|
| Extension | The local extension that is assigned to the device. |
| Name | The name of the user the device/extension is assigned to. |
| Language | The language to use on the device userinterface. |
| CallWaiting | Sets the call waiting state. On brand Snom it can be on or off, on all other models it is 1 or 0. |
| DND | Do not disturb set on the phone. On brand Snom it is on or off, on Yealink 1 or 0. Not filled in on other brands. |
| CustomConfig | Declares where in the configuration file, custom user defined configuration is inserted. |
| MasterPin | PBX wide master pin code. |
| Softkeys | |
| SoftkeyStart | The template section between this and SoftkeyEnd is looped for each softkey, and inside the loop SoftkeyFunction, SoftkeyLabel and SoftkeyIndex relates to the actual softkey. |
| SoftkeyEnd | See above. |
| SoftkeyIndex | The index of the softkey the function is to be applied to. |
| SoftkeyFunction | The function a softkey is to perform. |
| SoftkeyLabel | The text label to apply to the softkey. |
| SoftkeyValue | The value the softkey should activate. For a BLF or SPEEDDIAL it is a phone number or extension, for a URL it's the URL to call. |
| SoftkeyBlfBlindTransfer | Yealink only: 2 when the phone's BLF keys do blind transfer, 1 when they do attended transfer (the default). Example: transfer.dsskey_deal_type = %SoftkeyBlfBlindTransfer% |
| Network | |
| NetworkDHCP | Specifies if DHCP should be enabled. For brand Snom it can be on or off, on all other phones it is 1 or 0. |
| NetworkDNS1 | If no DHCP, this is the primary DNS server. |
| NetworkDNS2 | If no DHCP, this is the secondary DNS server. |
| NetworkGateway | If no DHCP, this is the default gateway. |
| NetworkIP | If no DHCP, this is the the IP address. |
| NetworkSubnet | If no DHCP, this is the subnet mask. |
| NetworkVlanId | If VLAN is required, this is the VLAN to use, defaults to 0. |
| NetworkVlanPriority | If VLAN is required, this is the VLAN priority. |
| Authentication | |
| Username | Username for authenticating the device against the PBX. |
| Password | Password for authenticating the device against the PBX. |
| Server | Hostname of the SIP server the device must connect to - sip.telecomx.dk. |
| Audio | |
| AudioHandsetSpeaker | Audio level for handset speaker. |
| AudioHandsetMicrophone | Audio level for handset microphone. |
| AudioHandsfreeSpeaker | Audio level for device base speaker. |
| AudioHandsfreeMicrophone | Audio level for device base microphone. |
| AudioHeadsetSpeaker | Audio level for headset speaker. |
| AudioHeadsetMicrophone | Audio level for headset microphone. |
| AudioRinger | Audio level for ringer (ringtone). |
| HeadsetButton | Configuration of dedicated headset button on the phone. |
| Dhsg | 1 when the phone uses a DHSG headset, otherwise 0 (Mitel and Yealink). |
| Ringtone | The ringtone to use. |
| RingtoneCustom | If ringtone is custom, ID of ringtone. |
| Display (Mitel and Yealink) | |
| DisplayBrightness | Display brightness, 0-15. |
| DisplayBrightnessIdle | Display brightness when the phone is idle, 0-15. |
| DisplayBackground | URL of the picture shown as display background, empty when there is none. |
| DisplayBackgroundName | Yealink only: the file name of the background picture (the last part of DisplayBackground), empty when there is none. |
| DisplayFontColor | Font color of the idle screen: white when the phone is set to LIGHT, otherwise blue. |
| Handsets (for multi handset devices) | |
| HandsetStart | The template section between this and HandsetEnd is looped for each handset. Inside the loop HandsetIndex is maintained and all variables, except for Network variables are for the individual handset device. |
| HandsetIndex | The index of the handset. |
| HandsetId | A string that identifies the individual handset. |
| HandsetIndexM300 | Snom M300 only: the bit of the handset in the subscribed handsets mask, 1 for handset 1, 2 for handset 2, 4 for handset 3 and so on. Example: <subscr_sip_ua_subscribed_hs idx="%HandsetIndex%">%HandsetIndexM300%</subscr_sip_ua_subscribed_hs> |
| HandsetEnd | The end of the handset loop. See HandsetStart. |
| Mac | Mac address of the device. |
| Configuration check | |
| CheckSyncTime | Time of day for the nightly configuration check, HH:MM on a 24-hour clock from 02:00 to 03:59. Each phone gets a fixed time from a hash of its MAC address (its id when it has no MAC address), so the phones do not all ask at the same minute. Example (Mitel): auto resync time: %CheckSyncTime% |
| uaCSTA | |
| UaCsta | true when the phone model has capabilities.uacsta and the phone has not opted out (PbxSipPhones.uacsta is not false), otherwise false. Meant for an IF block that switches the brand's CSTA settings on: %%IF UaCsta="true"%% ... %%ENDIF UaCsta%%. |
| Conditional | |
| IF | Start of IF section: %%IF <Variable>=/!="Value"%%. Variable is any on this list, value may be quoted or not. Example: %%IF NetworkDHCP=true%% |
| ENDIF | End of IF section: ENDIF <Variable>%%. Example: %%ENDIF NetworkDHCP%%. |
On brand Grandstream, NetworkDNS1, NetworkDNS2, NetworkGateway, NetworkIP and NetworkSubnet can also be specified with a postfix that specifies the part of the IP address from 0-3, e.g. NetworkIP.0, NetworkIP.1, NetworkIP.2, NetworkIP.3. A part the address does not have, e.g. when no second DNS server is set, is empty. Works from tcx-api 2.27.7; before that the postfixed keywords were left in the file as they were.