Edit

Translate phone numbers to an alternate format

  • Article
  • Applies to:
    Microsoft Teams

This article describes how to translate numbers for outbound and inbound calls to an alternate format. This is step 4 of the following steps for configuring Direct Routing:

For information on all the steps required for setting up Direct Routing, see Configure Direct Routing.

Sometimes tenant administrators may want to change the number for outbound and/or inbound calls based on the patterns they created to ensure interoperability with Session Border Controllers (SBCs). This article describes how you can specify a Number Translation Rules policy to translate numbers to an alternate format.

You can use the Number Translation Rules policy to translate numbers for the following:

  • Inbound calls: Calls from a PSTN endpoint (caller) to a Teams client (callee)
  • Outbound calls: Calls from a Teams client (caller) to a PSTN endpoint (callee)

The policy is applied at the SBC level. You can assign multiple translation rules to an SBC, which are applied in the order that they appear when you list them in PowerShell. You can also change the order of the rules in the policy.

To create, modify, view, and delete number manipulation rules, use the New-CsTeamsTranslationRule, Set-CsTeamsTranslationRule, Get-CsTeamsTranslationRule, and Remove-CsTeamsTranslationRule cmdlets.

To assign, configure, and list number manipulation rules on SBCs, use the New-CSOnlinePSTNGateway and Set-CSOnlinePSTNGateway cmdlets together with the InboundTeamsNumberTranslationRules, InboundPSTNNumberTranslationRules, OutboundTeamsNumberTranslationRules, and OutboundPSTNNumberTranslationRules parameters.

Note

The maximum total number of translation rules is 400, maximum translation parameter name length is 100 symbols, maximum translation parameter pattern length is 1024 symbols, and maximum translation parameter translation length is 256 symbols.

Example SBC configuration

For this scenario, the New-CsOnlinePSTNGateway cmdlet is run to create the following SBC configuration:

New-CSOnlinePSTNGateway -Identity sbc1.contoso.com -SipSignalingPort 5061 –InboundTeamsNumberTranslationRules ‘AddPlus1’, ‘AddE164SeattleAreaCode’ -InboundPSTNNumberTranslationRules ‘AddPlus1’ -OutboundPSTNNumberTranslationRules ‘AddSeattleAreaCode’,‘StripPlus1’  -OutboundTeamsNumberTranslationRules ‘StripPlus1’

The translation rules assigned to the SBC are summarized in the following table:

Name Pattern Translation
AddPlus1 ^(\d{10})$ +1$1
AddE164SeattleAreaCode ^(\d{4})$ +1206555$1
AddSeattleAreaCode ^(\d{4})$ 425555$1
StripPlus1 ^\+1(\d{10})$ $1

In the following examples, there are two users, Alice and Bob. Alice is a Teams user whose number is +1 206 555 0100. Bob is a PSTN user whose number is +1 425 555 0100.

Example 1: Inbound call to a ten-digit number

Bob calls Alice using a non-E.164 ten-digit number. Bob dials 2065550100 to reach Alice. SBC uses 2065550100 in the RequestURI and To headers and 4255550100 in the From header.

Header Original Translated header Parameter and rule applied
RequestURI INVITE sip:2065550100@sbc.contoso.com INVITE sip:+12065550100@sbc.contoso.com InboundTeamsNumberTranslationRules ‘AddPlus1’
TO TO: <sip:2065550100@sbc.contoso.com> TO: <sip:+12065550100@sbc.contoso.com> InboundTeamsNumberTranslationRules ‘AddPlus1’
FROM FROM: <sip:4255550100@sbc.contoso.com> FROM: <sip:+14255550100@sbc.contoso.com> InboundPSTNNumberTranslationRules ‘AddPlus1’

Example 2: Inbound call to a four-digit number

Bob calls Alice using a four-digit number. Bob dials 0100 to reach Alice. SBC uses 0100 in the RequestURI and To headers and 4255550100 in the From header.

Header Original Translated header Parameter and rule applied
RequestURI INVITE sip:0100@sbc.contoso.com INVITE sip:+12065550100@sbc.contoso.com InboundTeamsNumberTranslationRules ‘AddE164SeattleAreaCode’
TO TO: <sip:0100@sbc.contoso.com> TO: <sip:+12065550100@sbc.contoso.com> InboundTeamsNumberTranslationRules ‘AddE164SeattleAreaCode’
FROM FROM: <sip:4255550100@sbc.contoso.com> FROM: <sip:+14255550100@sbc.contoso.com> InboundPSTNNumberTranslationRules ‘AddPlus1’

Example 3: Outbound call using a ten-digit non-E.164 number

Alice calls Bob using a ten-digit number. Alice dials 425 555 0100 to reach Bob. SBC is configured to use non-E.164 ten-digit numbers for both Teams and PSTN users.

In this scenario, a dial plan translates the number before sending it to the Direct Routing interface. When Alice enters 425 555 0100 in the Teams client, the number is translated to +14255550100 by the country/region dial plan. The resulting numbers are a cumulative normalization of the dial plan rules and Teams translation rules. The Teams translation rules remove the "+1" that was added by the dial plan.

Header Original Translated header Parameter and rule applied
RequestURI INVITE sip:+14255550100@sbc.contoso.com INVITE sip:4255550100@sbc.contoso.com OutboundPSTNNumberTranslationRules ‘StripPlus1’
TO TO: <sip:+14255550100@sbc.contoso.com> TO: <sip:4255555555@sbc.contoso.com> OutboundPSTNNumberTranslationRules ‘StripPlus1’
FROM FROM: <sip:+12065550100@sbc.contoso.com> FROM: <sip:2065550100@sbc.contoso.com> OutboundTeamsNumberTranslationRules ‘StripPlus1’

Example 4: Outbound call using a four-digit non-E.164 number

Alice calls Bob using a four-digit number. Alice uses 0100 to reach Bob from Calls or by using a contact. SBC is configured to use non-E.164 four-digit numbers for Teams users and ten-digit numbers for PSTN users. The dial plan isn't applied in this scenario.

Header Original Translated header Parameter and rule applied
RequestURI INVITE sip:0100@sbc.contoso.com INVITE sip:4255550100@sbc.contoso.com InboundTeamsNumberTranslationRules ‘AddSeattleAreaCode’
TO TO: <sip:0100@sbc.contoso.com> TO: <sip:4255555555@sbc.contoso.com> InboundTeamsNumberTranslationRulesList ‘AddSeattleAreaCode’
FROM FROM: <sip:+12065550100@sbc.contoso.com> FROM: <sip:2065550100@sbc.contoso.com> InboundPSTNNumberTranslationRules ‘StripPlus1’

See also

Plan Direct Routing

Configure Direct Routing