Use Case - Routing Unassigned Numbers to Nimbus

Reroute unassigned telephone numbers directly to a Nimbus service using PowerShell.

In this use case, you will learn how to reroute unassigned telephone numbers directly to a Nimbus service using PowerShell. This can be useful to catch any range of unused or abandoned numbers in your company to redirect them to a standard service instead.


  • You require Teams Administrator rights to create the necessary Teams configuration items
  • At least one Nimbus service is set up, of which you need to retrieve the Application Instance Object ID

🔍 Note: Contents in this use case are based on the official Microsoft Documentation: Routing calls to unassigned numbers

Show Icon Legend

💡 = A hint to signal learnings, improvements or useful information in context. 🔍 = Info points out essential notes or related page in context.
☝ = Notifies you about fallacies and tricky parts that help avoid problems. 🤔 = Asks and answers common questions and troubleshooting points.
❌ = Warns you of actions with irreversible / data-destructive consequence. ✅ = Intructs you to perform a certain (prerequired) action to complete a related step.

Considerations & Limitations

The service taking your calls underlies Microsoft licensing constraints, especially when your "Catch All" service is redirecting to other PSTN numbers. Also refer to the notes from the Microsoft Documentation

To route calls to unassigned Microsoft Calling Plan subscriber numbers, your tenant needs to have available Communications Credits.

To route calls to unassigned Microsoft Calling Plan service numbers, your tenant needs to have at least one "Phone System – Virtual User license".

Related to these notes, the following PSTN license limitations for first level response services apply for Nimbus services:


Out-of-the-box, Nimbus and affiliated addons can only perform PSTN transfers according to Microsoft's licensing and constraints.

Which PSTN license do I need to acquire?

✅ As a tenant administrator you need to acquire the following licenses and assign them to the application instance of the respective Nimbus SOURCE service (team) that will act as PSTN transferor:

Your Setup Required License
Direct Routing "Microsoft Teams Phone Resource Account"
Calling Plan "Microsoft Teams Phone Resource Account"
+ "Microsoft Teams Domestic Calling Plan" or "Microsoft Teams Domestic and International Calling Plan" or "Microsoft Teams Calling Plan pay-as-you-go"+ "Communication Credits" (if these aren't already included as part of your plan)
Operator Connect "Microsoft Teams Phone Resource Account"

☝ As of 2023 "Microsoft Teams Phone Standard" licences are no longer supported by Microsoft. Previously those licenses were viable for Nimbus. → Regardless if you are using Direct Routing, Calling Plans, Operator Connect - the "Microsoft Teams Phone Resource Account" license is now always required

☝ Please note that Luware staff cannot make recommendations on which license plan is best suited for your needs. Depending on your scenario, additional Teams App licenses may be required. Exact details are to be discussed with your Microsoft contacts.

🔍 Also see:


How does PSTN licensing affect Service and Call Transfers?

Assuming that Service A has a PSTN license assigned - but further Services don't - the following scenario may unfold:


  • Scenario A - Service A workflow is configured to transfer the caller to Service B. The license of Service A is used, the PSTN transfer occurs. The PSTN license is re-used throughout further transfers to Services C..D...x.
  • Scenario B - Service B is called directly instead. Now the workflow of Service B attempts a redirect to either service A or transfer to C. The PSTN transfer fails due to a missing license on Service B.


  • For one first-level-response Service: If you handle first-response calls always via the same Service you need a PSTN license for that particular first-level Service.
  • For multiple first-level-response Services: If you handle first-response calls always via multiple Services you need a PSTN license for all those first-level Services .
  • Nimbus will attempt to use the PSTN license of the first service that responded to a call, regardless of how many further internal service transfers are performed thereafter.
  • If no PSTN license is found on a service that requires it for a transfer, the transfer task will be considered as failed and be treated as such by the system (e.g. workflow exit announcement, reporting "transfer failed" outcome).

☝ Note that handling and tracking of running cost for PSTN licenses is outside of Luware support scope.
If you require assistance in extending and/or configuring your Nimbus services for PSTN our support will gladly assist you:

🔍 Refer to the external reference: Microsoft Teams PSTN connectivity options and Microsoft Teams add-on licenses.


PowerShell Script Execution

  1. Start a Powershell Session and connect to Microsoft Teams using your Teams admin permissions. 
  2. Adapt the following code to match your requirements before executing it in your PowerShell session:
Identity & Description Free of choice. This is how you identify the rule later for editing and deletion.
Pattern Any regular expression. The default shown here reroutes exactly one specific number, but you can adapt this to a range or use wildcards as you like.
Target Replace with your Nimbus UPN, which you can retrieve from the Service Settings > "General" Tab.
TargetType Leave this set to "ResourceAccount"
TreatmentPriority Instructs Microsoft Teams how to prioritize this treatment, e.g. if you are using multiple unassigned number treatments for overlapping number ranges.  
Leave this set to 1 to ensure that Teams will route all calls to the specified number pattern over to the Nimbus service first.
$UnassignedNumberTreatment = @{
                                                         Identity = "UNT_Nimbus"
                                                         Description = "Route to Nimbus"
                                                         Pattern = "^\+41123456789$"
                                                         TargetType = "ResourceAccount"
                                                         Target = (Get-CsOnlineApplicationInstance -Identity <Nimbus Service UPN>).ObjectId
                                                         TreatmentPriority = 1
                                                        New-CsTeamsUnassignedNumberTreatment @UnassignedNumberTreatment

Check Results

After the script execution you should get a result as follows. 

Identity : UNT_ITHelpdesk  
TreatmentId : UNT_ITHelpdesk  
Pattern : ^\+41123456789$  
TargetType : ResourceAccount  
Target : 578c7d49-0015-49b8-963b-d8010dcc1cea  
TreatmentPriority : 1  
Description : Catch old number and reroute to IT Service Desk

💡 Via "Get-CsTeamsUnassignedNumberTreatment" you can retrieve previous rules and adapt them accordingly.

Table of Contents