Phone Number Translations

Various interaction between Service Cloud Voice and Cisco CCE depend on Phone number translations. Due to international differences and customer specific applications, a customizable tool is needed to transfer phone numbers from format A to format B.

caution

The b+s Connects for Service Cloud Voice solution automatically removes all characters except numbers, hashtags (#), asterisks (*), commas (,) and leading plus signs (+). It also removes the first occurrence of (0).

This will be done BEFORE your Phone Number Translations are applied.

This guide describes how to configure phone number translations.

Fields

Phone number translations are stored in Name-Value fields. This allows you to configure an unlimited amount of rules per feature.

info

The configuration is stored as a JSON string.

Note that backslashes need to be escaped e.g. \d+ becomes \\d+.

{"Remove all characters but digits":"[1,17]->[^\\d]+","To internal number":"[7,17]->(\\d{7})(\\d{4})->$2"}

The field Name is technically not used. It is there to add a human readable string in order to quickly identify the purpose of this rule. Good names are for example: Remove all leading zeros, Add leading plus etc.

Creating translation rules

Rules are provided as Regular Expressions. To be more accurate: The JavaScript implementation of Regular Expressions.

tip

A good way to start is by reading the RegExp document from the MDN web docs.

Nevertheless, creating complex Regular Expressions is often cumbersome. Therefore we added extra syntax to make configuration as easy as possible.

The figure below shows the general syntax of a phone number translation rule:

Predicate

The predicate is used to specify an interval defining the length of the number to match.

The predicate above specifies that all numbers with a length between 7 and 11 characters (including edges + spaces) match.

tip

Predicates always match the original length of the number. This helps in simplifying the configuration by reducing the risk of colliding rules for internal / external numbers.

Pattern

The Pattern specifies the format of the number to match.

The pattern above states that the number must consist of digits only and selects them.

Selector

Selectors define the final format of the number. If characters / digits need to be added which were not originally present, this is the place to do it.

The selector is the last step in building the number. Based on the pattern output, the selector builds up the new number.

Example 1

The following example shows how to transfer a number received from the Contact Center in the format of 0319175200 to the Swiss E164 format +41 31 917 52 00.

info

This example uses two translation rules (1. and 2.)

The first rule in this example actually does not change the number. For numbers between 1 and 17 characters in length, anything else but digits would be removed. Since there is no non-digit present, nothing changes.

The second rule applies to numbers which are exactly 10 characters long (originally). 0319175200 matches and therefore the rule gets applied. The pattern specifies that the number must start with a group of one digit (\d{1}), followed by a group of two digits (\d{2}) followed by a group of three digits (\d{3}) and so on.

The selector then accesses the pattern groups to define the new number string. This means $2 references the first (\d{2}) and therefore contains 31.

Example 2

The following example shows how to transfer a number received from the Contact Center in the format +14693150217 to the US E164 format +1 469 315 0217.

info

This example uses two translation rules (1. and 2.)

1. This number is exactly 12 characters long, so the rule “Add spaces to US Numbers” is applied
2. (\+1) says that the number must start with +1. If the number is 12 characters long, but does not start with a +1, the rule is canceled and nothing is changed.
3. (\d{3}) says that +1 must be followed by 3 digits
4. (\d{3}) says that the last 3 digits must be followed by another 3 digits
5. (\d{4}) says that the last 3 digits must be followed by 4 digits

If any of this does not match, the number will not be changed.

So all of the rules apply for “+14693150217”. Therefore the number is changed by “$1 $2 $3 $4”:

1. $1 refers to the group (\+1), the number to send to Service Cloud Voice looks like +1
2. $2 refers to the first of the two (\d{3}), the number to send to Service Cloud Voice looks like +1 469
3. $3 refers to the second of the two (\d{3}), the number to send to Service Cloud Voice looks like +1 469 315
4. $4 refers to the last group (\d{4}), the number to send to Service Cloud Voice looks like +1 469 315 0217

The spaces in the replacement part of the rule “$1 $2 $3 $4” are used directly. So if you use “$1-$2-$3-$4” the number would be translated to: +1-469-315-0217

And you are also allowed to remove groups: [12, 12]->(\+1)(\d{3})(\d{3})(\d{4})->$2 $3 $4 will be translated to: 469 315 0217 . [12, 12]->(\+1)(\d{3})(\d{3})(\d{4})-> $3 $4 will be translated to: 315 0217.

It is also possible to convert an international US number to a local one like: [12, 12]->(\+1)(\d{3})(\d{3})(\d{4})->($2) $3-$4

Then the incoming number “+14693150217” will be translated to: (469) 315-0217.

Example 3

The following example shows how to transfer a number received from the Contact Center in the format of +491515555531 to the German E164 format +49 151 5555 531.

info

This example uses two translation rules (1. and 2.)

1. This number is exactly 13 characters long, so the rule “Add spaces to German Numbers” is applied
2. (\+49) says that the number must start with +49. If the number is 13 characters long, but does not start with a +49, the rule is canceled and nothing is changed.
3. (\d{3}) says that +49 must be followed by 3 digits
4. (\d{4}) says that the last 3 digits must be followed by 4 digits
5. (\d{3}) says that the last 4 digits must be followed by 3 digits

If any of this does not match, the number will not be changed.

So all of the rules apply for “+491515555531”. Therefore the number is changed by “$1 $2 $3 $4”:

1. $1 refers to the group (\+49), the number to send to Service Cloud Voice looks like +49
2. $2 refers to the first of the two (\d{3}), the number to send to Service Cloud Voice looks like +49 151
3. $3 refers to the second of the two (\d{4}), the number to send to Service Cloud Voice looks like +49 151 5555
4. $4 refers to the last group (\d{3}), the number to send to Service Cloud Voice looks like +49 151 5555 531

The same applies as for rule one. You can use the replacement part $1 $2 $3 $4 to choose what to use from the number.

More Translation Regex examples

Description	Translation Regex
Remove all characters but digits	[1,17]->[^\d]+
Remove all characters but digits & +	[1,17]->[^+\d]+

Description	Translation Regex
Remove +1	[12,12]->(.{1})(\d{1})(\d{10})->$3
Remove +1	[10,12]->(^\+1+)(\d+)->$2
Remove +49	[10,15]->(^\+49+)(\d+)->$2
Remove +49	[10,15]->(.{1})(\d{2})(\d{9})->$3
Remove +41	[10,13]->(^\+41+)(\d+)->$2
Remove +41	[10,13]->(.{1})(\d{2})(\d{9})->$3
Remove +XX	[10,14]->(^\++)(\d{2})(\d+)->$3

Description	Translation Regex
Remove + and replace it with zeros US E164	[10,12]->(.{1})(\d{1})(\d{10})-> 001 $3
Remove +1 and replace it with zeros US E164	[10,12]->(^\+1+)(\d+)-> 001$2
Remove + and replace it with zeros DE E164	[12,15]->(.{1})(\d{2})(\d{10})-> 0049 $3
Remove +49 and replace it with zeros DE E164	[10,12]->(^\+49+)(\d+)-> 0049$2
Remove + and replace it with zeros CH E164	[10,13]->(.{1})(\d{2})(\d{9})-> 0041 $3
Remove +41 and replace it with zeros CH E164	[10,12]->(^\+41+)(\d+)-> 0041$2

Description	Translation Regex
US Number with Space	[12,17]->(\d{1})(\d{3})(\d{3})(\d{4})->+1 $2 $3 $4
US Number with Space	[12,17]->(\+1)(\d{3})(\d{3})(\d{4})->$1 $2 $3 $4
DE Number with Space	[12,17]->(\d{2})(\d{3})(\d{4})(\d{3})->+49 $2 $3 $4
DE Number with Space	[12,17]->(\+49)(\d{3})(\d{4})(\d{3})->$1 $2 $3 $4
CH Number with Space	[12,17]->(\d{2})(\d{2})(\d{3})(\d{2})(\d{2})->+41 $2 $3 $4
CH Number with Space	[12,17]->(\+41)(\d{2})(\d{3})(\d{2})(\d{2})->$1 $2 $3 $4