Chapter 10: Digit Manipulation

Cisco Press

You can perform digit manipulation only on H.323 and SIP gateways; on MGCP gateways, the call agent must perform any manipulation because it controls the calls. Cisco CallManager Express and routers that are using Survivable Remote Site Telephony (SRST) offer some additional manipulation options to those discussed in this chapter, such as dial plan patterns. CallManager Express techniques are beyond the scope of this book. Chapter 13, "SRST and MGCP Gateway Fallback," discusses SRST digit manipulation in greater detail. You can also use Toolkit Command Language (Tcl) scripts to manipulate the called and calling numbers, as described in Chapter 15, "Using TCL Scripts and VoiceXML."

Table 10-1 Digit Manipulation Techniques

TechniqueWhere You Apply ItWhen Action Is TakenWhat Can Be Manipulated
Digit stripping (default router action)To POTS1 dial peerAfter outbound dial peer is matched, but before digits are sent outCalled number only
Forward digitsTo dial peerAfter outbound dial peer is matched, but before digits are sent outCalled number only
Prefix digitsTo dial peerAfter outbound dial peer is matched, but before digits are sent outCalled number only
Number expansionGlobally, applies to all callsBefore outbound dial peer is matchedCalled number only
CLIDTo dial peerAfter outbound dial peer is matched, but before digits are sent outCalling numbers, calling name
Voice translation profilesTo dial peer, voice port, trunk group, all incoming VoIP2 calls, Source IP group, or NFAS3 interfaceCan translate before incoming dial peer is matched, before outgoing dial peer is matched, or before call is set upCalling, called, and redirecting numbers; numbering plan; numbering type; and calls

1 POTS = Plain old telephone service

2 VoIP = Voice over IP

3 NFAS = Non-Facility Associated Signaling

Digit Stripping

VoIP dial peers transmit all digits in the called number by default; however, POTS dial peers remove, or strip, any outbound digits that explicitly match their destination pattern. For instance, given a destination pattern of 55512.. the called number transmitted to the PSTN would contain just the last two digits. The first five digits, 55512, would be stripped. Only explicitly matched digits are stripped. Given a destination pattern of 555[2-9].. and a digit string of 555422, only the 555 would be stripped. If all the digits in a called number are removed, the caller hears only a reorder tone.

Digit stripping is the default behavior of POTS dial peers. It can work to your advantage, as long as you understand its effect. For instance, if users dial 9 to reach an outside number, you would not want the number 9 sent to the PSTN as part of the called number. When you configure the destination pattern of a POTS dial peer as 9T, the 9 is matched, so it is stripped. The remaining digits are transmitted. However, suppose that you have a dial peer for an emergency number, such as 911 in the United States. In that case, you would not want any of those digits removed, so you must disable the default behavior for that dial peer.

You can disable digit stripping with the command no digit-strip under POTS dial-peer configuration mode. Re-enable it with the command digit-strip. The relevant command syntax is as follows:

dial-peer voice 1 pots
[no] digit-strip

Forward Digits

You can achieve more precise control over the number of digits in the called number that are transmitted to the PSTN with the following command, which applies only to POTS dial peers:

forward-digits [number | all | extra]


  • number gives the number of digits to be forwarded.

  • all means to forward all digits.

  • extra tells the gateway to forward any digits that are longer than the length of the destination pattern.

This command lets you specify the exact number of digits to be forwarded. If the number of digits presented exceeds the number allowed, the rightmost digits are sent. One place this can be useful is when you must dial a code (such as 9) to reach an outside number, and there is an emergency situation. The previous section showed how to ensure that the entire emergency number (such as 911) is sent. In an emergency, a person might be confused about whether to dial the outside code. That is why dial peers are typically set up to match both the emergency number, and that number plus the code number. If the destination pattern of a dial peer is 9911, you should send only 911. You can use the forward-digits command to transmit only the last three digits, 911, to the PSTN.

The following examples show what digits are sent when you dial the number 111-222-3333 and use various options of the forward-digits command.

For this first case, the rightmost seven digits, 222-3333, are sent.

Miami(config)#dial-peer voice 111 pots
Miami(config-dial-peer)#destination-pattern 111222....
Miami(config-dial-peer)#forward-digits 7

With the configuration that follows, the entire number, 111-222-3333, is sent. This is an alternative to using the no digit-strip command shown in the previous section.

Miami(config)#dial-peer voice 111 pots
Miami(config-dial-peer)#destination-pattern 111222....
Miami(config-dial-peer)#forward-digits all

Finally, with the final configuration that follows, because the destination pattern is now six digits long and the dialed number is ten digits, the "extra" digits—3333—are sent.

Miami(config)#dial-peer voice 111 pots
Miami(config-dial-peer)#destination-pattern 111222
Miami(config-dial-peer)#forward-digits extra

Prefix Digits

In some cases, you might need to transmit more than the dialed digits of a called number. For example, perhaps a call that would normally go across your VoIP network needs to be rerouted through the PSTN, requiring the addition of the appropriate area code and prefix. Or, a destination pattern might specify the first six digits of the number, with wildcards for the other digits. By default, those six digits are stripped. You can use the prefix string command to replace some of those digits. This command is given under dial-peer configuration mode, and it is only for POTS dial peers. The prefixed string can be any number from 0 to 9 and a comma that inserts a one-second pause. The gateway prefixes digits after the outgoing dial peer is matched and after any digits are stripped, but before it sends out the call.

In Example 10-1, long-distance calls need to go to a particular carrier and must have a separate dial peer from external local calls. The destination pattern is 91 to capture long-distance traffic; however, the PSTN needs the number 1 transmitted as part of the called number to route the call properly. Thus, the prefix command is added to replace that digit.

Example 10-1 Prefixing Digits to an Outgoing Call

Miami(config)#dial-peer voice 91 pots
Miami(config-dial-peer)#destination-pattern 91T
Miami(config-dial-peer)#prefix 1
Miami(config-dial-peer)#port 1/0:23

When a user dials the outside long-distance number 9-1-111-222-3333, the digits are manipulated before being sent to the PSTN. The original digits 9 and 1 are stripped, and a 1 is prefixed to the remaining number. Thus, the PSTN receives the number 1-111-222-3333.

Number Expansion

Number expansion is another way to add digits to an outgoing called number; however, number expansion is applied to the gateway as a whole, and acts on all calls, not just those matching a designated dial peer. As with the previous three techniques, this manipulates only the called number. Number expansion manipulation occurs before any outbound dial peer is matched. Thus, you must configure outbound dial peers to match the expanded numbers, not the original ones.

The command for number expansion is num-exp original-number expanded-number, configured at global configuration mode. Although it is called number expansion, the manipulated number can contain fewer digits than the original, or it can contain more.

Example 10-2 shows two instances of number expansion configured. The first expands any four-number extension beginning with 1 to a seven-digit number beginning with 5551. The second changes any seven-digit number beginning with 5551 to a four-digit extension.

Example 10-2 Number Expansion

Miami(config)#num-exp 1... 5551...
Miami(config)#num-exp 5551... 1...
!Verifying the first number expansion
Miami#show dialplan number 1111
Macro Exp.: 5551111
!Verifying the second number expansion
Miami#show dialplan number 5551098
Macro Exp.: 1098

In the results of the show dialplan number command, notice that although the number entered in the command is the original number, the router looked for a match to the expanded number. The show dialplan number command is also useful for verifying that you have a dial peer to match the expanded number.

Voice Translation Rules and Profiles

You can accomplish more precise, granular manipulation using voice translation profiles, which contain voice translation rules. The techniques that were previously discussed can alter only the called number, or dialed number identification service (DNIS), digits. Translation profiles are much more powerful. They can change both the DNIS and the calling number, or automatic number identification (ANI), digits plus the redirecting number. With translation profiles you can adjust the numbering type and plan, reject unwanted calls based on a rule match, and remove specific digits (such as hyphens).

A legacy technique called translation rules (without the voice) can manipulate ANI and DNIS numbers. This technique is still supported, but the recommended method is to use voice translation rules and voice translation profiles.

Using voice translation profiles for digit manipulation requires three steps:

  1. Create one or more voice translation rules and a prioritized list of translations associated with each rule. A maximum of 128 rules is supported, with 15 translations per rule.

  2. Create one or more voice translation profiles and associate the translation rules to the profile. You can define up to 1000 profiles, each with its own unique name. Within the profile, you can apply one voice translation rule to calling numbers, one to called numbers, and one to redirected called numbers.

  3. Apply the voice translation profile to all VoIP calls globally, a dial peer, a voice port, a trunk group, a source IP group, or an interface.

Creating Voice Translation Rules

To create a voice translation rule, use the command voice translation-rule tag in global configuration mode. Then create an ordered list of one or more rules with the following command:

rule precedence /match pattern/ /replace pattern/ [type {match-type replace-type} 
  [plan {match-type replace-type}]]

You can enter rules in any order; the precedence value determines the order in which the rules are executed. You can configure up to 15 rules.

A basic voice translation rule replaces one group of digits with another. Each group is delineated with // (frontslash) characters. In Example 10-3, voice translation Rule 1 replaces 111 with 222, and 333 with 444. A test of the translations shows that they are carried out as specified.

Example 10-3 Using a Basic Voice Translation Rule

Boise(config)#voice translation-rule 1
Boise(cfg-translation-rule)#rule 1 /111/ /222/
Boise(cfg-translation-rule)#rule 2 /333/ /444/

Boise#test voice translation-rule 1 111
Matched with rule 1
Original number: 111  Translated number: 222
Original number type: none   Translated number type: none
Original number plan: none   Translated number plan: none

Boise#test voice translation-rule 1 13335
Matched with rule 2
Original number: 13335 Translated number: 14445
Original number type: none   Translated number type: none
Original number plan: none   Translated number plan: none

When the number 1335 is tested, notice that the number patterns are translated no matter where they appear in the string. Notice also that any digits that are not expressly matched—the numbers 1 and 5 in this example—are simply carried through. For more precise control, you can use some special characters and wildcards to build regular expressions, as shown in the next section.

Building Regular Expressions

A regular expression is a text-parsing tool that combines a string of literal characters and special characters, called metacharacters. Voice translation rules can use regular expressions to find matches in the digit strings, and replace a match with a different string. Table 10-2 lists some commonly used special characters and their meaning.

Table 10-2 Regular Expression Special Characters

.Matches any single character
[ ]Matches one number within the brackets; for example, the expression [234] would match either 2, 3, or 4
[^ ]Matches a number except one within the bracket
-Indicates a range of numbers when used within brackets
^When used before a string, denotes the beginning of a string
$Denotes the end of a string
*Matches 0 or more occurrences of the previous expression
+Matches 1 or more occurrences of the previous expression
?Matches 0 or 1 occurrence of the previous expression (use Ctrl-v ? to enter in the IOS)
( )Groups digits into sets
\Changes the meaning of the following character
&Brings all the matched digits into the replacement string

Previously in Example 10-3, the string 333 was matched even when it was in the middle of the list. If you wanted to match 333 only when it appeared at the beginning of a string, you could use the caret character:

rule 2 /^333/ /444/

To match a string containing only 333, add the dollar sign at the end and the caret at the beginning:

rule 2 /^333$/ /444/
1 2 3 4 Page 1
Page 1 of 4
The 10 most powerful companies in enterprise networking 2022