How to Assign a Telephone Number to a Teams Calling API Bot/Application

In essence, assigning a telephone number to a Teams Calling Application/Bot involves creating a contact in Teams that points to the Application/Bot Id and assigning a phone number to that Teams contact. The Teams contact is called an "Application Instance". There are 4 steps:

1. Create the Application/Bot registration
2. Create an Application Instance
3. Assign a Virtual User License (or Phone System license) to the Application Instance
4. Assign a Phone Number to the Application Instance

1. Create the Application/Bot registration

If you are using an Application/Bot created by another vendor, just ask them what the App ID is. They will know what to give you.

If you have written an Application/Bot using the Microsoft Teams Calling API's then you need to create an application/bot registration if you haven't already. Here is how:

https://microsoftgraph.github.io/microsoft-graph-comms-samples/docs/articles/calls/register-calling-bot.html

What you will need from the "Azure Bot Service" is the  "Microsoft App Id" from your application. 

This Microsoft App Id will be used in the ApplicationId parameter of the next step.

2. Create an Application Instance

As Teams tenant Administrator, run the below Powershell:

New-CsOnlineApplicationInstance -UserPrincipleName <user@contoso.com> -ApplicationId "<app_id>" -Displayname "<bot_display_name>"

UserPrincipleName = The username you want to create for this application instance.
ApplicationId = The app id from step 1
DisplayName = The display name you want to give this contact.

When you run this command successfully it will give output including an ObjectId. This ObjectId will be used in the Sync-CsOnlineApplicationInstance command.

Sync-CsOnlineApplicationInstance -ObjectId <application_instantce_id>

ObjectId = ObjectId output from New-CsOnlineApplicationInstance you just ran.

NOTE: We needed to wait 1 hour before we could do step 3 below and about 10 hours before we could do step 4. To know when you can do step 3, just search for the contact you made in this step in the Microsoft Teams client, when it is available to Teams users, you can do step 3. To know when you can do step 4, call the contact and see if the Application/Bot answers, when it does you can do step 4. If you try step 4 before that you will get an error something like "WARNING: The following Application Instance not present in BVD..."

3. Assign a Virtual User License (or Phone System license) to the Application Instance

You can follow these instructions to assign a Virtual User License to the Resource Account:

https://docs.microsoft.com/en-us/microsoftteams/teams-add-on-licensing/virtual-user

In my tenant these steps worked:

Browse to: https://admin.microsoft.com/AdminPortal/Home#/users

Find the useraccount/application instance/resource account we created in step 2.

Click "Manage product licenses" (located in header)

Select Location = United States
Check "Phone System - Virtual User"

Click "Save Changes" button.

Exit using "X" button (upper right)

4. Assign a Phone Number to the Application Instance

To see what Service Numbers are available to assign to this Application Instance go to:

Skype for Business admin center navigate to: Admin center | Teams and Skype | Skype legacy admin | Voice | Phone Numbers

When you find an unassigned service number, copy it or write it down and use it in the PowerShell below. Now run:

Set-CsOnlineVoiceApplicationInstance -Identity <user@contoso.com> -TelephoneNumber <phone_number>

Conclusion

You should now be able to call the telephone number and reach your Teams Calling Application/Bot