Dialing Plans, Digitmaps, and digit replacement rules

How dialed digits are handled when making calls

Alexa built-in

What are Digitmaps and Digit Replacement Rules

When a person attempts to make a call using a telephone set, he/she would dial a stream of digits based on the appropriate dialing plan.  For example, in the U.S., a local call can be dialed with a 7 digit number whose leading digit is a number between 2 and 9, a long distance dialing will be a 1 followed by a 3-digit area code followed by a 7 digit number . In order to proceed with the dialing process in a timely and natural manner, the BuddyTalk device needs to know when the user has completed dialing and sends out the dialed number in a timely manner. This can be accomplished using Digitmaps.  Digitmaps are templates that match different sequences of digits that users dial as part of their interaction with their phone system.   

There may be cases in which a certain additional rules apply and some prefixes will be added to the normal dialing plan.  A caller using a (IP)phone behind an (IP-)PBX would be one such case.  Typically, a smaller number of digits (e.g., 4 digits) is used to represent an internal extension number, and  a prefix (e.g., 9) will need to be added to a PSTN number in order to make an external call,.  Such a prefix may also differ based on the call destination (e.g., 9 for local calls, 8 for long-distance calls).  Digit Replacment is a user friendly mechanism to allow a BuddyTalk user not to be concerned about the various prefix rules when the BuddyTalk device is configured as an IP-Phone extension to an IP-PBX.

Dialing Plans and Digimaps


A Digitmap should be constructed based on the Dialing Plan.  When a user uses an analog phone connected to the device’s FXS port to dial a phone number, the BuddyTalk device sends the digits out immediately when there is a match between the dialed digits and a digitmap rule to initiate the call. If there is no match, the device waits for the user to enter more digits, and will only send if there is a sufficient gap after the last digit or if the user presses the send key (#) to indicate the dialing is complete.

Here is how to configure the digitmap pattern which corresponds to the dial plan selected by the VoIP service operator or the IP-PBX.  The figure below shows the web GUI where the Digitmap and the Replacment Rule are to be enterned.

Navigate to Telephony > Profile Config.  Select the Profile you want to edit and click the edit icon.

Then, scroll down to the Digitmap Setting section.

Field Name Description

Define patterns of dial strings that the BuddyTalk device can send to the SIP server when the pattern has been met, and not have to wait for the InterDigit Time out or the Critical Timeout.  This helps improve call completion times.

Digitmap Timer
  • Critical Timeout: Short timeout if match digitmap T pattern (See Digitmap syntax).
  • Inter Digit Timeout: Time to wait between digits being dialed before assuming no more entries are to be made.  This is required to ensure a pause in dialing does not trigger an incomplete number to be sent to the SIP server.

Digitmap Syntax

A DigitMap, according to this syntax, is defined either by a (case insensitive) “String” or by a “list of strings” over which the SIP Device will attempt to find a shortest possible match. Regardless of the above syntax, a timer is only allowed if it appears in the last position in a string. Each string in the list is an alternate numbering scheme.

The formal syntax of the digitmap is described by the following notation:

  • Digit ::= “0” | “1” | “2” | “3” | “4” | “5” | “6” | “7” | “8” | “9”
  • Timer ::= “T” | “t” — matches the detection of a timer
  • Letter ::= Digit | Timer | “#” | “*” | “A” | “a” | “B” | “b” | “C” | “c” | “D” | “d”
  • Range :: = “x” — matches any single digit 

A Dial Plan and a Digitmap Example

Below is a dial plan example (a typical U.S. dial plan).

Digit(s) dialed Description
A local number. Example. 433 5589
Any dialed numbers followed by a “#” sign. Example: 8657#
Star services. Example: *76
A long distance number. Example: 1 408 669 1288
011 + up to 15 digits
An international number. Example: 011 65 65866110

The corresponding Digitmap for the Dial Plan above is given by:


A Dialing Plan and a Digitmap Example of a Typical IP-PBX system

Below is a typical IP-PBX dial plan example which uses 4 digits for internal extension numbers with the leading digit being from 2 to 7, and a 9 as the prefix for external calls.

Digit(s) dialed Description
Local Operator
An internal extension number. Example: 5587
A local number. Example. 9 433 5589
Any dialed numbers followed by a “#” sign. Example: 8657#
Star services. Example: *76
A long distance number. Example: 9 1 925 778 1029
9011 + up to 15 digits
An international number. Example: 9 011 65 65866110

The corresponding Digitmap for the Dial Plan above is given by:


Digit Replacement Rules


While the IP-PBX system Digitmap example given above can handle users dialing internal or external numbers, it is undesirable and inconvenient when the user is making phone calls using voice commands or through his/her Tablet Controller or Mobile App since it will require the user to change his/her Contacts on the Alexa App, the Tablet Controller, and the Mobile App.  In this case, a Digit Replacement Rule comes in handy.

Digit Replacement, when working in conjunction with a corresponding Digitmap, allows a user to make calls naturally and conveniently without changing his/her Contacts to accommodate for the required prefixes and special Dialing Plan corresponding to the IP-PBX, Consequently, the user can conveniently utilizes the user friendly voice commands, Tablet Controller, and Mobile App for dialing.

The Digit Replacement scheme operates on each Digitmap entry, and applies a specific Digit Replacement rule on the digits in each of the Digitmap entries.  The Digit Replacement Rules are separated by a vertical bar “|”, corresponding to the sequence of Digitmap entries.  Here are the replacement rules and their respective actions:
  • “/nnn”: add prefix digits nnn in front of the dialing string
  • “@/nnn”: replace all dialing string with digits nnn
  • “xxx/nnn”: replace matched digits xxx with digits nnn

Here is an example of the Digit Replacement scheme applied to the IP-PBX system example given above. The dialing plan of this IP-PBX system requires that a prefix be added to the following calling types:

  • 9: prefix. Domestic local calls, e.g., 9 4325400
  • 9: prefix. US national calls, e.g., 9 1 408 432 5400
  • 9: prefix. International calls, e.g., 9 011 65 68720828

 Here is the original Digitmap for this IP-PBX system:


Extending the Digitmap to account for calls initiated via voice commands, a Tablet Controller, or a Mobile App, we will have the following augmented Digitmap:


This expanded Digitmap allows users to dial with the prefix when dialing from a POTS phone or without a prefix when making calls using voice commands or through the Tablet Controller or Mobile App’s Contacts. 

To handle such numbers without the required prefix, the corresponding Digit Replacement Rules are:


The rules above automatically add the prefix 9 when the Digitmap matches [2-9]xxxxxxT, 1[2-9]xxxxxxxxxand 011x.T. It also replaces the “+” in the +x.T dialing (meaning a leading “+” and any number of digits with a pause longer than the timeout defined in the Digitmap timer rules) with 9011 for an external international dialing. With the Digitmap and Digit Replace Rules given above, here are the allowed dialing rules: 

  1. Dial 0 for local operator.
  2. Dial a 4 digit internal extension whose first digit can be from 2 to 7.
  3. Dial a 7-digit external local number with the prefix ‘9’ (the first digit of any local number cannot be 1).
  4. Dial a 7-digit external local number without a prefix.
  5. Dial a 11 digit external number with the prefix ‘9’.
  6. Dial a 11 digit external number without a prefix.
  7. Dial an international number using ‘011’ with or without a prefix.
  8. Dial a (international) number using ‘+’ (without a prefix).
  9. Immediate digit collection for dialing using ‘#’.
  10. Dial a star code.

Here is the resulting Digitmap and Replacement Rule Settings in the BuddyTalk’s GUI page:

Navigate to Telephony > Profile Config.  Select the Profile you want to edit and click the edit icon. Then, scroll down to the Digitmap Setting section.

The Digit Replacement process is applicable to the following calling methods:

  • Voice commands with either a contact name or a telephone number
  • BuddyTalk Mobile App through Dial Pad digit dialing, Contacts based dialing, or Call History based dialing
  • BuddyTalk Tablet Controller through Dial Pad digit dialing, Contacts based dialing, or Call History based dialing
  • FXS port POTS phone dialing

Please be aware that the use of Digitmap for voice commands, Tablet Controller, and Mobile App dialing is solely for the purpose of applying Digit Replacement Rules.  These three dialing methods do not use Digitmap to match and collect digits for dialing as when to dial is controlled by the user tapping the ‘Phone’ icon for Tablet Controller and Mobile App based calling.   

Please also note that when applying the Digitmap rules to the POTS phone dialing, the matching is conducted digit-by-digit as the user dials the phone number. Therefore, the first (shortest) match will trigger the software to discontinue to subsequent matches. When calling via voice commands, Tablet Controller, or the Mobile App, on the other hand, the Digitmap process finds the longest match and apply the corresponding Digit Replacement Rule to the matched digits.