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 making a call using a telephone set, the caller needs to 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 whose first digit can be between 2 to 9, 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 an 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 when making an external PSTN call,.  Such a prefix may also differ based on the call destination (e.g., 9 for local calls, 8 for long-distance calls).  Digit Replacement 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
Digimap

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
  • Position :: = “.” — matches an arbitrary number, including zero, of occurrences of th preceding construct 

A Dial Plan and a Digitmap Example

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

Digit(s) dialed Description
[2-9]xxxxxx
A local number. Example. 433 5589
[0-9*].#
Any dialed numbers followed by a “#” sign. Example: 8657#
*xx
Star services. Example: *76
1[2-9]xxxxxxxxxx
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:

 [2-9]xxxxxx|1[2-9]xxxxxxxxx|011x.T|[0-9*].#|*xx

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
0
Local Operator
[2-7]xxx
An internal extension number. Example: 5587
9[2-9]xxxxxx
A local number. Example. 9 433 5589
[0-9*].#
Any dialed numbers followed by a “#” sign. Example: 8657#
*xx
Star services. Example: *76
91[2-9]xxxxxxxxxx
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:

 0|[2-7]xxx|9[2-9]xxxxxx|91[2-9]xxxxxxxxx|9011x.T|[0-9*].#|*xx

Please note that while Digitmap is used to determine when the user has completed dialing and sends out the dialed number in a timely manner, it is only used in the FXS/RJ11 analog phone based call initiations.  It does not apply to the other BuddyTalk BT110 call initiation mechanisms, voice commands, Mobile App, and Tablet Controller based dialing as these call initiation mechanisms all have their respective clear and unambiguous dialing completion and dialing trigger mechanisms (e.g., voice commands based dialing is triggered when the user completes the Alexa call command “Alexa, call John Smith.”, “Alexa, call 1408-555-1212.”, and for the Mobile App and Tablet Controller, the calls are triggered when the user taps the phone button).    

While Digitmap is not used to capture dialed digit completion and trigger the dialing action for voice commands, Mobile App, and Tablet Controller based call initiation, it serves another important function: to match the call digit pattern and then apply the corresponding Digit Replacement Rules to modify the actual digits to be dialed.  This is described in the section below. 

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:

 0|[2-7]xxx|9[2-9]xxxxxx|91[2-9]xxxxxxxxx|9011x.T|[0-9*].#|*xx

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:

0T|[2-7]xxxT|9[2-9]xxxxxx|[2-9]xxxxxxT|91[2-9]xxxxxxxxx|1[2-9]xxxxxxxxx|9011x.T|011x.T|+x.T|[0-9*].#|*xx

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:

 /|/|/|/9|/|/9|/|/9|+/9011|/|/

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.

Another set of Digitmap and Digit Replacement Rules is given below.  It is designed for U.S. dialing rules (e.g., dial 1 first for long distance, local numbers are 7 digit long, long distance numbers are 10 digit long (plus a ‘1’), 011 for international calls, etc.). Additionally, it assumes 3-digit extensions and allows voice commands or Mobile App calling without using the prefix (using voice commands/Mobile App to call an external number without having to say/tap the prefix ‘9’, and for using voice commands/Mobile App calling an external contact name without having to add ‘9’ to the Contacts). 

Digitmap:

911|611|411|311|9911|9611|9411|9311|0T|[2-9]xxT|9[2-9]xxxxxxT|[2-9]xxxxxxT|91[2-9]xxxxxxxxx|1[2-9]xxxxxxxxx|9[2-9]xxxxxxxxx| [2-9]xxxxxxxxxT|9011x.T|011x.T|9+x.T |+x.T|[0-9*].#|9*xx|*xx

Digit Replacement Rules: 

/9|/9|/9|/9|/|/|/|/|/|/|/|/9|/|/9|9/91|/91|/|/9|9+/9011|+/9011|/|/|/9

  1. The first 8 entries are for these special numbers: 911, 611, 411, 311.  The user can just dial these numbers with or without the prefix ‘9’.
  2. The 9th entry: ‘0’ for local operator.
  3. The 10th entry: 3-digit extension dialing.
  4. The 11th and 12th entries: 7-digit local dialing, with or without the prefix ‘9’.
  5. The 13th and 14th entries: 11 digit (1 plus 10 digit) long distance dialing with or without the prefix ‘9’.
  6. The 15th entry: 9 (prefix for external dialing) plus 10 digit long distance dialing.
  7. The 16th entry: 10 digit long distance dialing without prefix ‘9’.
  8. The 17th and 18th entries: International dialing with 011, with or without the prefix ‘9’.
  9. The 19th and 20th entries: + to be replaced by 011, with or without the prefix ‘9’.
  10. The 21st entry: use ‘#’ to dial out.  Here, we assume that no digit replacement will take place, i.e., the user will need to start with a prefix for external dialing.
  11. 22nd and 23rd entries: star code ‘*xx’, with or without the prefix.

Another example of Digitmap and Digit Replacement Rules pair is given below.  It is designed for U.S. dialing rules (e.g., dial 1 first for long distance, local numbers are 7 digit long, long distance numbers are 10 digit long (plus a ‘1’), 011 for international calls, etc.). Additionally, the example assumes extensions to be 3-digit long, and allows voice commands or Mobile App calling without using the prefix (using voice commands/Mobile App to call an external number without having to say/tap the prefix ‘9’, and for using voice commands/Mobile App calling an external contact name without having to add ‘9’ to the Contacts). 

The color coding, a non-black color used in every 4th entry, is for ease of visual matching between the entries of the Digitmap and the Digit Replacement Rules.

Digitmap:

911|611|411|311|9911|9611|9411|9311|0T|[2-9]xxT|9[2-9]xxxxxxT|[2-9]xxxxxxT|91[2-9]xxxxxxxxx|1[2-9]xxxxxxxxx|9[2-9]xxxxxxxxx| [2-9]xxxxxxxxxT|9011x.T|011x.T|9+x.T |+x.T|[0-9*].#|9*xx|*xx

Digit Replacement Rules: 

/9|/9|/9|/9|/|/|/|/|/|/|/|/9|/|/9|9/91|/91|/|/9|9+/9011|+/9011|/|/|/9

  1. The first 8 entries are for these special numbers: 911, 611, 411, 311.  The user can just dial these numbers with or without the prefix ‘9’.
  2. The 9th entry: ‘0’ for local operator.
  3. The 10th entry: 3-digit extension dialing.
  4. The 11th and 12th entries: 7-digit local dialing, with or without the prefix ‘9’.
  5. The 13th and 14th entries: 11 digit (1 plus 10 digit) long distance dialing with or without the prefix ‘9’.
  6. The 15th entry: 9 (prefix for external dialing) plus 10 digit long distance dialing.
  7. The 16th entry: 10 digit long distance dialing without prefix ‘9’.
  8. The 17th and 18th entries: International dialing with 011, with or without the prefix ‘9’.
  9. The 19th and 20th entries: + to be replaced by 011, with or without the prefix ‘9’.
  10. The 21st entry: use ‘#’ to dial out.  Here, we assume that no digit replacement will take place, i.e., the user will need to start with a prefix for external dialing.
  11. 22nd and 23rd entries: star code ‘*xx’, with or without the prefix.

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.