Digit Maps
As mentioned in a previous post, there are two ways to dial SIP phone calls: with on-hook dialing and with off-hook dialing. This post will detail the differences and introduce the digit map and digit map timeout.
On-hook dialing
On-hook dialing is the simpler case so we’ll start with that. On-hook dialing means a number of digits are dialed while the phone is still on-hook (i.e., hungup). Once the desired number of digits have been entered, the phone is taken off-hook and the digits are sent to the call manager and a call is initiated. If the digits correspond to a valid telephone number or extension, then the call connects. If the digits aren’t a valid telephone number or extension, then the call manager will respond with some indication – typically a sequence tones or busy signal – that the call was invalid. This is how you dial cellular phone calls today.
Off-hook dialing
Off-hook dialing can be a bit more involved. Off-hook dialing means that the phone is taken off-hook, dialtone is heard in the room, and then a number of digits are entered by the user – typically by pressing keys on a touch panel or digits on a physical dialer. The complicated part of off-hook dialing is knowing when the phone thinks that enough digits have been entered to initiate a call. For example, how does the SIP device know that you only want to dial a 4-digit extension vs. dialing a 10-digit long distance number? You don’t want the system waiting forever for you to enter more digits nor do you want the system to prematurely dial a call while you’re entering additional digits. With on-hook dialing, you are explicitly telling the phone when you are done dialing by taking the phone off-hook. With on-hook dialing, you don’t have that same definitive boundary.
Digit Maps
Digit maps solve the off-hook dialing ambiguity by providing guidance on what is a valid number to dial. Digit maps are templates, or sequences of valid phone number digit strings separated by the vertical bar character “|”, used to match against the digits a user is entering. Digit maps only apply to the off-hook dialing scenario, which is useful to remember when trying to troubleshoot them later – you can always dial calls the way you expect by using on-hook dialing and then troubleshooting the digit map.
With off-hook dialing, whenever the dialed digits match an entry in the digit map template, the SIP device will send those digits to the call manager to initiate a call. If there is not a match, the SIP device waits for the user to enter more digits or eventually times out and sends the digits that it has collected to that point. Digit maps were defined as part of the IETF RFC 3435, and the syntax is defined in detail there. Most SIP interfaces follow this definition of digit maps although some, for example Symetrix Inc., use a custom format – see their documentation for how to use their digit map.
Digit Map Example
To learn to interpret the digit map, let’s look at a commonly used digit map:
[2-9]11|0T|011xxx.T|[0-1][2-9]xxxxxxxxx|[2-9]xxxxxxxxx|[2-9]xxxT
This digit map shows there are 6 matching options ([2-9]11 through [2-9]xxxT), each separated by the vertical bar “|”. Digit maps are processed left to right so more specific matches are positioned earlier in the digit map and less specific matches are positioned later. The following table describes the matching patterns.
| [2-9]11 | Matches any 3 digit extension starting with 2 through 9 combined with the digits 1 and 1. For example, this matches the sequences of 211, 311, …, 911 and will then dial those digits immediately once a match has been found. |
| 0T | Matches the digit 0 and, after a time-out of 3 seconds (defined in the Digit map Time-out), will send the 0 digit to the call manager. The “T” character specifies that a time-out will be used to determine when to send the digits to the call manager. |
| 011xxx.T | Matches any number starting with 011 which has three digits or more between 0 and 9. The ‘.’ Character matches zero or more occurrences of the preceding match, which in this case is any digit. A matching dial string will be dialed after a time out of 3 seconds after the last digit is entered. This is the typical international long distance dialing string used in the US. An example match is: 0112312345678. |
| [0-1][2-9]xxxxxxxxx | Matches any number starting with a 0 or a 1 followed by any digit between 2 and 9 and then followed by exactly 9 digits. This is the typical 10-digit long distance dialing in North America. An example match is 16786537090. |
| [2-9]xxxxxxxxx | Matches any number starting with a 2 through 9 and then followed by any 9 digits. This is the typical 10-digit local calling requirement of many North America regions. An example match is 6786537090. |
| [2-9]xxxT | This will match any four-digit extension starting with the digits 2 through 9 followed by 3 more digits. After the last digit is entered the system will pause for the time-out and then dial the extension. An example match is: 2854. |
Digit Map Time out
The default time-out, how long the system will wait before it dials the digits collected so far, is 3 seconds. This value can easily be changed by editing the digit map time-out. The digit map time-out is typically a string of the form 3|3|3|3|3|3 with the same number of vertical bars “|” as used in the digit map. To change the time-out for a particular digit map, change the digit in the corresponding location in the digit map time-out.
For example, to change the time out of the last entry in the digit map to 5 seconds,
[2-9]11|0T|011xxx.T|[0-1][2-9]xxxxxxxxx|[2-9]xxx.T
Set the digit map time-out to: 3|3|3|3|5. If there are two many digit map time-out values, they are ignored. If there are too few values, the default value is 3 seconds.
What’s Important to remember
The digit map should match a customer’s dialing plan. For example, if they are used to dialing 4 digit extensions, make sure 4 digit extensions are supported so they don’t have to wait for the digit map timeout before the digits are sent to the call manager and the call initiated.
If you are working with a SIP device and can dial the phone just fine on-hook but are having troubles dialing the types of phone numbers that users dial with off-hook dialing, then you need to spend more time on the digit map. Ask the local IT or phone team what is the numbering plan they have in place for dialing phone calls. Are 4-digit extensions used? 5-digit extensions used? Do you have to dial a 9 to get an outside line, etc. Once you have that information, build a simple digit map to test against the call manager and keep incrementally improving it until you’re comfortable with it.
