How to use Lightweight Bot and Azure Automation to interact with Teams Call Queue (with examples)

Hi All,

have you ever wondered how to give to end users a way to interact, change or update a Teams Auto Attendant or a Call Queue without needs to use the Teams Admin Center or PowerShell and without any Admin roles?

The first example of that needs is an “On Call Service” Teams Call Queue that some users have to transfer to different mobile numbers every shift change.
The second example is an emergency trigger that a user can run to transfer every Teams Call Queue calls to a different Call Queue.

In this article I will show how to achieve that using Azure Automation Runbooks and a MS Teams Lightweight Bot, nearly for free!

In this article you will find:

  • COMING SOON -> Example #2: Emergency Call Queue transfer to a different Call Queue

Azure Automation setup

1. Azure Automation Account creation

The first step is to create an Azure Automation Account in your Azure subscription.

  1. On the Microsoft Azure portal click on Create a resource
  1. Search for Automation and click Create
  1. Enter the information like the example below
  1. The new resource will be created in few seconds

2. Add Teams PowerShell Module

Now that we have an Azure Automation Account, we have to add the PowerShell module used in our Runbooks.

  1. Go to the Azure Automation Account just created, scroll the left menu to Shared Resources -> Modules.
    We need the Teams PowerShell module, that is not present by default.
    To add it, click on Browse gallery
  1. Enter “teams” into the search area, the MicrosoftTeams PowerShell module will appear. Click on it
  1. When you are into the MicrosoftTeams PowerShell module, click on Select

Choose Runtime version then click on Import

  1. You will see the message “Module import is in progress”
  1. If you return to the Modules page, you will see that the MicrosoftTeams module is present with the Import Status
  1. After few minutes the Status will change to Available

3. Add Azure Automation Credentials

What we need now is a set of Credentials to be used by Azure Automation into our Runbooks.

In this example I use a technical account with these (recommended) settings:
Sync Status: Cloud only
Username format:
Password: extremely complex and set to Never Expire
Roles: Teams Service Admin
Licenses: none
MFA: not supported

It’s very important to understand that Runbooks do not have directly access to Account Credential.
Username and Password are set only in the next step and will never be directly used in the Runbooks

  1. Go to Credentials and click on Add a credential

2. Enter the information to create a new Credential set.
The value entered in the Name field will be the name of the Credential set and it will be used in the Runbooks

3. Now you have a Credential set to be used your Runbooks.

Example #1: “On Call Service” Teams Call Queue redirection

The first example of that needs is an “On Call Service” Teams Call Queue that some users have to transfer to different mobile numbers every shift change.

1. Call Queue settings and Identity

I’ll not cover how to create a Teams Call Queue in this article, if you need information on that process follow this article in Microsoft Docs: Create a call queue

Note: remember to assign a PSTN Usage Policy to the Call Queue Resource Account, with the Grant-CsOnlineVoiceRoutingPolicy cmdlet, to allow outbound call from the Call Queue to the PSTN.

The idea is to set the Call Queue to an immediate transfer (Call time out wait set to 0) and to use Azure Automation to change the redirection target number.

Before we can proceed to the Runbooks step, we need the Identity of the “On Call Service” Call Queue.
To obtain it, connect to Microsoft Teams via PowerShell (more information here), run this command and copy the Identity value of the Call Queue.

Get-CsCallQueue | select Name,Identity

2. Runbook and Webhook setup

  1. Go to Azure -> Azure Automation Account -> Process Automation -> Runbooks -> Create a runbook -> insert the Name and select PowerShell as Runbook type -> Create
  1. Copy and Past the following code into the Runbook, be sure to replace <AzureAutomationCredential> and <CallQueueIdentity> with your own values.
    [Parameter (Mandatory = $false)]
    [object] $WebhookData

# Retrieve Queue Number from Webhook request body
$Body = (ConvertFrom-Json -InputObject $WebhookData.RequestBody)
$Body.Text -match "(\d+)"
$NewQueueNumber = $Matches.0

# Authenticate to Teams
$Credential = Get-AutomationPSCredential -Name '<AzureAutomationCredential>'
$Session = Connect-MicrosoftTeams -credential $Credential

# Set Queue Number
Set-CsCallQueue -Identity <CallQueueIdentity> -TimeoutActionTarget "tel:$NewQueueNumber"
  1. Click Publish to complete the Runbook creation
  1. In the Runbook page, click Add webhook
  1. Follow the sequence, enter the Name you prefer (I suggest to use the same name for Webhook and Runbook), be sure to raise the Expiration data and copy the Webhook URL to a safe place (there is no way to retrieve it later)

3. Ligthweight Bot setup (outgoing webhook)

The last step is to add a Microsoft Teams Lightweight Bot (outgoing webhook) to a Team, normally this is the Teams used by the On Call Service Operators and Managers.

It’s important to undersand that everyone that can access the Team where you will add the Bot, will be able to trigger the Bot and change the Call Queue settings.

You can find more information on outgoing webhook here.

  1. Open Microsoft Teams and enter the designated Team -> click 3 dots next to the Team’s Name -> Manage team
  1. Click on the Apps Tab then on Create an outgoing webhook in the bottom of the page.
  1. The Name of the Lightweight Bot will be the command used in Teams to trigger the Runbook, so choose it wisely, it should be easy to remember for users.
    In this example I use TransferTo as the name of the Lightweight Bot, so users will invoke it with @TransferTo <mobile#>
    Paste the Webhook URL into the Callback URL field then click Create
  1. Even if we will not use it, copy the Security token when appear and store it.
  1. The Lightweight Bot (Outgoing Webhook) is ready and listed in the Apps Tab

4. How to use it

One of the most important aspect of this solution is that it’s very easy to use.

The On Call / On Duty Operator that needs to receive calls on his mobile phone number (for example 1234567), it will simply have to write the name of the Lightweight Bot and it’s mobile number, for example
@TransferTo 1234567
To be sure, wait 30-60 seconds then verify that incoming calls to the Call Queue will be redirect to On Call / On Duty Operator mobile number.
That’s it.

Note: The Outgoing Webhook will always reply with the message “Sorry, there was a problem encountered with your request”. This is an expected behaviour and it’s not related to any specific problem. Simply ignore it

5. How to check it

  1. If you want to check what happened, open the Azure Automation Runbook, you should see the list of recent jobs, status and time.
    Click one to see details
  1. The Job Input details will show you the WEBHOOKDATA arrived from Teams Lightweight Bot (you will see the mobile number entered after the Bot name)
  1. The Output details will show you the Set-CsCallQueue command results with the value set in the TimeoutActionTarget field
  1. In All Logs you should see 0 Errors and 0 Warnings
  1. In the Teams Admin Center -> Call Queue settings, you should see the mobile number entered by the last On Call Operator.

COMING SOON -> Example #2: Emergency Call Queue transfer to a different Call Queue

As always, I hope this solution could be helpful to some of you.
Best Regards


13 thoughts on “How to use Lightweight Bot and Azure Automation to interact with Teams Call Queue (with examples)

Add yours

  1. Cool scenario Luca.
    I used your example completely, however I get multiple errors when I execute the webhook.

    Any ideas how to troubleshoot?
    It looks like the errors are coming from somewhere out of the PS script.

    Liked by 1 person

  2. Hi Luca,

    Nice, just the solution we need!

    Only we get errors when the code runs in the runbook?
    It seems that the authentication goes wrong when we look in the recent jobs of the Azure Automation Runbook

    New-CsOnlineSession doesn’t excist anymore in the latest Teams Powershell module
    How do we get this code run right when we want to authenticate with Connect-MicrosoftTeams

    Liked by 1 person

  3. very interesting article. I’m looking for something similar, I mean changing the business hours of an auto attendant. I can’t find anything about this topic. Can you give me an advise?


  4. Hi Luca, thanks for your article. This works great. i was wondering if you can start the bot from Power Automate in some way. So instead of typing @ForwardTo number. just starting a Power Automate script


  5. Hi Luca, My ideal setup should be that its possible to click on a button in a Team within Microsoft Team to trigger the forward to a pre defined external number. So a kind of switchboard with one, two, … buttons or sliders to forward to the different destinations. This instead of calling the bot @ForwardTo and giving the external destination number. Thanks in advance for your advice.


Leave a Reply

Please log in using one of these methods to post your comment: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Blog at

Up ↑

%d bloggers like this: