Skip to main content

Microsoft Teams Integration

You can use the “Direct Routing” feature of Microsoft Teams to integrate with the Vodia PBX, explained on Microsoft® site here:

https://docs.microsoft.com/en-US/microsoftteams/direct-routing-configure

Especially “Plan Direct Routing” and “Configure Direct Routing”. This document presents it in a single step by step process to present it in a simplified way for integrating with the Vodia PBX, including the steps required on the Vodia PBX side.

Pre-Requisites​

  1. You need a Microsoft Teams account with a domain in Teams with FQDN (fully qualified domain name) that you own.
  2. One or more users in Teams that supports direct routing. Not all users in the domain need to have that license. Those licenses typically require an E3 (and an extra license for the direct routing) or E5 license.
  3. Make sure "Prevent toll bypass and send calls through the PSTN" setting in the calling policy of the user is set to Off. That will allow direct routing, especially if you are also using the MS phone system. It is found in Microsoft Teams admin center under the left side menu item "Voice" -> "Calling policies". Then choose the calling policy the user is using and make sure this setting is turned "Off".
  4. Vodia PBX software with TEAMS integration (introduced in version 64.1). For this you will need either the hosted PBX edition or a collaboration license from Vodia.
  5. A tenant (which is FQDN) in Vodia PBX with a valid certificate. The certificate can be a certificate signed by one of the Microsoft-approved Root CA. Certificates obtained by the PBX through LetsEnrypt also work.
  6. If you want to use a certificate signed by a Microsoft-approved Root CA, Then you will have to follow the general certificate creation process through CSR. You will have to create a CSR for your tenant and send it to be signed by the Root CA, while keeping the private key secure with you. Once it is signed by the Root CA, you can import it together with the private key you have as a domain certificate to Vodia PBX under the Certificate import section.
  7. The setup is a lot easier if the PBX runs on a public IP address. It is also possible to run the setup on a private address, but this requires a proper setup of the firewall and additional steps on the PBX to make access from the Microsoft servers possible to the PBX.

Vodia PBX setup for integration with TEAMS​

In order for Vodia PBX to send calls to TEAMS users, you have to:

  1. Create a tenant in Vodia PBX with an FQDN
  2. Create the Teams extensions in that tenant
  3. Create a Teams trunk in that tenant
  4. Create a general trunk in that tenant for the trunk calls and set it accordingly

1. Create a tenant in Vodia PBX​

Go to the tenant list. Press “Create” to add a new tenant. Give it a name that is an FQDN that:

  • Resolves to the Vodia PBX. That means that the Microsoft servers must be able to resolve that name to the address of the PBX.

  • The domain part of which is the same as the domain you create in Teams (explained in Teams section of this document).

  • Has a valid certificate.

Since in this example we will be creating a domain by the name of “company.com” in TEAMS done below, we can use the FQDN “pbx.company.com” for the tenant name to be created in Vodia PBX (the domain part of which, i.e. “company.com”, is the same as the domain name created in TEAMS). This FQDN “pbx.company.com” should reach the Vodia PBX and will be used by TEAMS to connect to Vodia PBX, explained in TEAMS section below. It must also have a valid certificate, which can be added through the certificates section. Or if the “Let’s encrypt” setting on Vodia PBX is on, then it will be created for you automatically.

A new tenant “pbx.company.com” will appear in the Vodia PBX tenant list.

2. Create the Teams extensions in that tenant​

  • Go to the tenant pbx.company.com that you created in step 1, by clicking on it

  • Go to “Extensions” under “Accounts”

  • Press “Add”

  • Enter the extension number, say 4002. Press “Create” to create the extension.

  • The extension will appear in the list. Click on it to enter for settings.

  • Under the “General” tab, enter the "Teams number" which must be the same as the telephone number you will give to the corresponding Teams user (explained in Teams section). Press save. That’s how the PBX will map this extension to the Teams user.

  • Also set the setting "Include Mictosoft Teams when calling the extension" to "Yes", and save.

  • Similarly, make all the extensions, giving them the Teams numbers to be mapped to the Teams users with the same numbers.

3. Create a Teams trunk in that tenant​

  • Go to the tenant pbx.company.com that you created in step 1, by clicking on it

  • Go to “SIP Trunks” under Trunks

  • Add a trunk by pressing the “Add” button

  • Select the provider as “Teams”

  • For “User name”, give a friendly name, say “Teams”

  • Press “Create”

  • The new “Teams” trunk will appear in the list.

  • Click on it for setup. Set the setting "Country code" to your country code.

Once you have also set up TEAMS, as explained in TEAMS section below, you should be able to make and receive calls to/from TEAMS users on this trunk. In this example, we will use the default setup (i.e. without changing anything, except the country code, on this trunk). The users (with their extension numbers) on TEAMS will act as the PBX extensions as they are mapped to the PBX extensions.

4. Create a general trunk for the trunk calls and set it up accordingly​

Create a general trunk for trunk calls the same way as in step 3, except choose your SIP trunk of choice (and NOT Teams), and give it another name for the general calls. It will be used for your outgoing and incoming trunk calls, as they are normally used.

  • Go to the tenant pbx.company.com that you created in step 1, by clicking on it

  • Go to “SIP Trunks” under Trunks

  • Add a trunk by pressing the “Add” button

  • Select your provider if available, otherwise select a generic one by choosing "Other"

  • For “User name”, give a friendly name, say “SIP Trunk”

  • Press “Create”

  • The new “SIP Trunk” trunk will appear in the list.

  • Click on it for setup. Set the setting "Country code" to your country code and any other setting

  • For example, you can set the "proxy address" to be UDP sip:yourproxy.com;transport=udp, TCP sip:yourproxy.com;transport=tcp or TLS sip:yourproxy.com;transport=tls

  • For example, you can set it for all incoming calls going to a specific account like “Auto Attendant” or “ACD” from where they can be distributed to different extensions including the mapped Teams users etc.

  • Also like any trunk, the Dial plan is used for using this trunk for outbound calls. The trunk will follow the rules for presenting the caller-ID (ANI) like with all other outbound calls. If you want to present a specific caller-ID, you can use the rule from-teams (starting in version 65.0.5).

TEAMS setup for integration with Vodia PBX​

  1. Login to your TEAMS account and create your domain there with FQDN that you own (e.g. company.com).
  2. Then create users under that domain and assign them E3, E5 or relevant license that supports “Direct Routing”.
  3. Create a PSTN gateway that will connect to the Vodia PBX using the FQDN of the domain you created in Vodia PBX with a valid certificate.
  4. Assign the Teams user a phone number. The user should be able to receive calls from the Vodia PBX now.
  5. Configure voice routing for outgoing calls to the Vodia PBX.

1. Create your domain in Teams​

Use your browser (if not using premises installation), login to your Teams admin account and create your domain. In “Microsoft Teams admin center”, go to “Setup”, then press the “View” button for the “Get your custom domain set up”, then the “Manage” button. Add a domain there. Choose a domain name (e.g. company.com) that you own. Since it will be verified by Microsoft for example by having you paste a value in the TXT value field of your DNS or signing in to the account where you got the domain etc. it is important that you own the domain and can perform the verification process. Once that is done, the domain will be created and you can add users to it.

2. Create users in that domain​

Now you can create users under the domain you just created in step 1 above. Again, in “Microsoft Teams admin center”, go “Active users” under “Users” and “Add a user”. Give the first and last name of the user (say “John Smith”) and under username give a unique name that will be his/her email, but make sure to choose the domain you created above for the domain part of the username (company.com in this example) and not the default company.onmicrosoft.com or any other *.onmicrosoft.com. That way the user will reside in the domain you just created in step 1 above (in this example say: js@company.com).

3. Create a PSTN gateway that will connect to the Vodia PBX using MS Teams UI​

(Alternative way for this step through PowerShell instead of Teams UI is given at the end)

  • Login to Microsoft Teams as admin
  • Click on "Admin" to enter Microsoft Teams admin center
  • In the left menu panel, click on "Show all" so that you can see Teams option
  • Click on "Teams" to enter Microsoft Teams admin center
  • In the left menu panel, expand the "Voice" option
  • Then click on "Direct Routing"
  • Under the SBCs tab, click "Add" to add a new SBC (PSTN gateway)
  • A form will open
  • Simply add the FQDN for the SBC (that is the FQDN of the domain that had been added in the Vodia PBX, in our example, pbx.company.com)
  • Set the "SIP signaling port" to 5061
  • Press "Save"
  • The new SBC (PSTN Gateway) will appear in the list of SBCs

4. Assign the Teams user a phone number using MS Teams UI​

(Alternative way for this step through PowerShell instead of Teams UI is given at the end)

  • Login to Microsft Teams as admin
  • Click on "Admin" to enter Microsoft Teams admin center
  • In the left menu panel, click on "Show all" so that you can see Teams option
  • Click on "Teams" to enter Microsoft Teams admin center
  • In the left menu panel, expand the "Users" option
  • Then click on "Manage users"
  • Click on the user, in our example, John Smith
  • Click on the "Edit" button (in Account tab)
  • On the right side "Assign phone number" panel should open
  • Select "Phone number type" as "Direct Routing"
  • Set the "Assigned phone number" as the "Teams number" in the extension that you set in Vodia PBX above to be mapped to, in this example, 4002
  • Note: You will only be able to do this if your user has the right license to allow it
  • Press "Apply" button to save
  • A phone number should now be assigned to this Teams user which is the same teams number in the Vodia PBX tenant
warning

Notice, the number is a 4 digit number for our example. This number acts as an extension number for this Teams user because it is mapped to the same exact extension number (4002) that was created in the Vodia PBX domain. It can call and be called as an extension between TEAMS and Vodia PBX. PSTN or SIP trunk inbound and outbound calls can be handled by the Vodia PBX regular trunk just like any PBX and users on TEAMS can act as extensions of the PBX.

info

Note: It can take some time between creating a user in Teams and being able to change its setting here with "Set-CsUser", so you may have to wait an hour or two if it gives errors like the user does not exist and you have made sure that the user email (or name) is correct.

The user should be able to receive calls from the Vodia PBX now, either from extensions on Vodia PBX itself or from PSTN and SIP trunks (setup within Vodia PBX), as the case may be.

5. Configure voice routing for outgoing calls to the Vodia PBX using MS Teams UI​

(Alternative way for this step through PowerShell instead of Teams UI is given at the end) You can configure the rules as to when to use the PSTN gateway, that was setup in step 3 above, to route the call to Vodia PBX.

As explained in the Microsoft document, Microsoft Phone System has a routing mechanism that allows a call to be sent to a specific SBC based on:

  • Called number pattern

  • Called number pattern + Specific User who makes the call

Call routing involves:

  • Online PSTN Gateway: It connects to the SBC or PBX (in this case, Vodia PBX). It also stores the configuration that is applied when a call is placed via the SBC, such as forward P-Asserted-Identity (PAI) or Preferred Codecs. It is used by Voice Routes.

  • Voice Route: It uses Online PSTN Gateways to use for calls where calling number matches the pattern.

  • PSTN Usage: It uses Voice Routes and other PSTN Usages. Different Voice Routing Policies can use it.

  • Voice Routing Policy: It uses PSTN Usages. It can be assigned to a user or to multiple users.

In summary: User -> Voice routing policy -> PSTN usage -> Voice route -> PSTN gateway

In our example, since we use the user as a PBX extension of Vodia, we want the call to first go there and use the dial plans in Vodia PBX for routing calls. There can be other scenarios easily implemented as well. For this simple one, let’s create:

John Smith (User)-> Policy1 (Voice policy) -> Usage1 (PSTN usage) -> Route1 (Voice route) -> pbx.company.com (PSTN gateway)

Let’s create the route using the Vodia PSTN gateway:​

  • Login to Microsoft Teams as admin
  • Click on "Admin" to enter Microsoft Teams admin center
  • In the left menu panel, click on "Show all" so that you can see Teams option
  • Click on "Teams" to enter Microsoft Teams admin center
  • In the left menu panel, expand the "Voice" option
  • Then click on "Direct Routing"
  • Click the "Voice routes" tab and under the "Voice routes" tab, click "Add" to add a new voice route
  • A form will open
  • Simply add the voice route name, in our example, Route1
  • Set the "SIP signaling port" to 5061
  • Set the Priority as 1
  • Set the Dialed number pattern as: ^(\+1[0-9]+)$
  • Click "Add SBCs"
  • In the new form on the right, select the SBC (PSTN Gateway) we created above, i.e. pbx.company.com
  • Press "Apply" and the new SBC will appear in the list
  • Now click "Add PSTN usage" to create a new usage
  • In the new form on the right, first add a new usage by clicking on "Add", giving it a name, Usage1, then press "Save and apply"
  • Now click "Add PSTN usage" to add the usage already created
  • In the new form on the right, select the usage Usage1 just created
  • Press "Apply" and the new usage will appear in the list
  • Press "Save" to complete the Voice route creation and it will appear in the list under the "Voice routes" tab

As you can see we created a route “Route1” where TEAMS will pass the call to PSTN gateway pbx.company.com (a domain in Vodia PBX) if the dialed number has at least 4 numbers (that is of course based on our example here where we want to give each user a 4 digit extension, but it is up to your setup), with or without a + sign. That way, you could dial a 4 digit extension or an E.164 number with country code and + sign.

Of course, multiple routes can be created with different priorities.

Let’s create a voice policy using the same usage to which our PSTN gateway is linked above:​

  • Follow the same steps above to enter Microsoft Teams admin center
  • In the left menu panel, expand the "Voice" option
  • Then click on "Voice routing policies"
  • Click "Add" to add a new policy to the list
  • A new form will open
  • Give the name for your voice routing policy, in our example, Policy1
  • Now click "Add PSTN usage"
  • In the new form on the right, select the usage Usage1 that was already created above during voice route creation
  • Press "Apply" and the usage will appear in the list
  • Press "Save" to complete the Voice routing policy creation and it will appear in the list of Voice routing policies

You can, of course, create a policy with several PSTN Usages, but we will keep it simple and to the point regarding our example.

Let’s grant our user John Smith our voice policy:​

  • Follow the same steps above to enter Microsoft Teams admin center
  • In the left menu panel, click on "Users" to show the list of users
  • Click on the user (John Smith in our example) to whom you want to grant our voice policy
  • Click on the "Policies" tab
  • Click on "Edit" of Assigned policies
  • A new form will appear on the right
  • In that form, under Voice routing policy dropdown menu, select our policy Policy1
  • Click "Apply" and the Voice policy will be selected

Now the outbound dialing policy and routing is complete and John Smith can call out. In this example, that outbound call will end up in your Vodia PBX domain pbx.company.com.

In our example, we could set up your domain in Vodia PBX (explained in Vodia PBX section) so that:

  • If that extension (4 digits in this case) exists in your Vodia PBX domain and registered, it will be called from your Teams user whether its a SIP desktop phone registered to your Vodia domain, Vodia desktop app, Vodia web app or Vodia smartphone app.

  • If that extension does not exist (say an E.164 10 digit number etc.), then Vodia will route the call to a PSTN gateway or SIP trunk so that call can go out.

The setup is complete. Below we give an alternative way to do the above steps 3, 4 and 5 through PowerShell, instead of through the Teams UI as done above.

Alternatively, steps 3, 4 and 5 can be done through PowerShell​

Setup of PowerShell to connect to your Teams account has been explained on Microsoft site here:

https://docs.microsoft.com/en-us/office365/enterprise/powershell/manage-skype-for-business-online-with-office-365-powershell

Just the portion “Connect using a Skype for Business Online administrator account name and password” should be enough unless you want to do more.

(Alternative way for step 3 above) Create a PSTN gateway that will connect to the Vodia PBX​

Before you use PowerShell, make sure it is the right one and connected to the right account as you did in step 3 above. To confirm that step 3 was done correctly use the command: Get-Command *onlinePSTNGateway*

Your command will return the four functions shown here that will let you manage the SBC.

CommandTypeNameVersionSource
FunctionGet-CsOnlinePSTNGateway1.0tmp_v5fiu1no.wxt
FunctionNew-CsOnlinePSTNGateway1.0tmp_v5fiu1no.wxt
FunctionRemove-CsOnlinePSTNGateway1.0tmp_v5fiu1no.wxt
FunctionSet-CsOnlinePSTNGateway1.0tmp_v5fiu1no.wxt

Using PowerShell, create a PSTN gateway that will connect to the Vodia PBX using the FQDN of the domain you create in Vodia PBX with a valid certificate. The domain portion of this FQDN must match the domain registered in your tenant as in step 1 above (e.g. it can be: pbx.company.com, since the domain you created was company.com). It is also important that there is a Teams user in that domain (as you did in step 2 above, a user in company.com) and an assigned E3 or E5 license. If not, you will receive an error: Can not use the “pbx.company.com” domain as it is not configured for this tenant.

This FQDN (say pbx.company.com) must resolve to a reachable IP of the Vodia PBX. Also, this FQDN (pbx.company.com in this example) must be a domain in Vodia PBX. Creating a domain in Vodia PBX is explained in the Vodia PBX section and you must make sure that a DNS A record is made for that domain (e.g. pbx.company.com) that will reach the Vodia PBX. Also, a valid certificate must be added in the Vodia PBX for this domain. Fortunately, it is very easy to get a valid certificate, if the “Let’s Encrypt” setting is on. All you have to do is create the domain and a Let’s Encrypt certificate will be added for it automatically.

PowerShell command example to create the PSTN gateway:

New-CsOnlinePSTNGateway -Identity pbx.company.com -Enabled $true -SipSignalingPort 5061 -MaxConcurrentSessions 100

Of course, use your own domain. Returns:

Identity              : pbx.company.com
Fqdn                  : pbx.company.com 
SipSignallingPort     : 5061 
FailoverTimeSeconds   : 10 
ForwardCallHistory    : False 
ForwardPai            : False 
SendSipOptions        : True 
MaxConcurrentSessions : 100 
Enabled               : True

You can check this gateway parameters at any time with:

Get-CsOnlinePSTNGateway -Identity pbx.company.com

Returns:

Identity              : pbx.company.com  
Fqdn                  : pbx.company.com 
SipSignallingPort     : 5061
CodecPriority         : SILKWB,SILKNB,PCMU,PCMA 
ExcludedCodecs        :  
FailoverTimeSeconds   : 10 
ForwardCallHistory    : False 
ForwardPai            : False 
SendSipOptions        : True 
MaxConcurrentSessions : 100 
Enabled               : True

(Alternative way for step 4 above) Assign the Teams user a phone number​

Direct Routing requires the user to be homed on Skype for Business Online. You can check this by looking at the RegistrarPool parameter. It needs to have a value in the infra.lync.com domain.

PowerShell command:

Get-CsOnlineUser -Identity "<User name>" | fl RegistrarPool

For our example:

Get-CsOnlineUser -Identity "John Smith" | fl RegistrarPool

Using PowerShell, enable the user for direct routing service by configuring the phone number and enabling enterprise voice and voicemail for the user.

Set-CsUser -Identity "<User name>" -EnterpriseVoiceEnabled $true -HostedVoiceMail $true -OnPremLineURI tel:<E.164 phone number>

For our example:

Set-CsUser -Identity "John Smith" -OnPremLineURI tel:4002 -EnterpriseVoiceEnabled $true -HostedVoiceMail $true

OR

Set-CsUser -Identity "js@company.com" -OnPremLineURI tel:4002 -EnterpriseVoiceEnabled $true -HostedVoiceMail $true

warning

Notice, the number is a 4 digit number for our example. This number acts as an extension number for this Teams user because it is mapped to the same exact extension number (4002) that was created in the Vodia PBX domain, explained in Vodia PBX section above. It can call and be called as an extension between TEAMS and Vodia PBX. PSTN or SIP trunk inbound and outbound calls can be handled by the Vodia PBX regular trunk just like any PBX and users on TEAMS can act as extensions of the PBX.

info

Note: It can take some time between creating a user in Teams and being able to change its setting here with "Set-CsUser", so you may have to wait an hour or two if it gives errors like the user does not exist and you have made sure that the user email (or name) is correct.

The user should be able to receive calls from the Vodia PBX now, either from extensions on Vodia PBX itself or from PSTN and SIP trunks (setup within Vodia PBX), as the case may be.

(Alternative way for step 5 above) Configure voice routing for outgoing calls to the Vodia PBX​

Now you can configure the rules as to when to use the PSTN gateway, that was setup in step 3 above, to route the call to Vodia PBX.

As explained in the Microsoft document, Microsoft Phone System has a routing mechanism that allows a call to be sent to a specific SBC based on:

  • Called number pattern

  • Called number pattern + Specific User who makes the call

Call routing involves:

  • Online PSTN Gateway: It connects to the SBC or PBX (in this case, Vodia PBX). It also stores the configuration that is applied when a call is placed via the SBC, such as forward P-Asserted-Identity (PAI) or Preferred Codecs. It is used by Voice Routes.

  • Voice Route: It uses Online PSTN Gateways to use for calls where calling number matches the pattern.

  • PSTN Usage: It uses Voice Routes and other PSTN Usages. Different Voice Routing Policies can use it.

  • Voice Routing Policy: It uses PSTN Usages. It can be assigned to a user or to multiple users.

In summary:

User -> Voice routing policy -> PSTN usage -> Voice route -> PSTN gateway

In our example, since we use the user as a PBX extension of Vodia, we want the call to first go there and use the dial plans in Vodia PBX for routing calls. There can be other scenarios easily implemented as well. For this simple one, let’s create:

John Smith (User)-> Policy1 (Voice policy) -> Usage1 (PSTN usage) -> pbx.company.com (PSTN gateway)

Let’s create the usage first as it is going to be used in the route:​

Set-CsOnlinePstnUsage -Identity Global -Usage @{Add="Usage1"}

To find out available usages, use:

Get-CSOnlinePSTNUsage

Let’s create the route using the Vodia PSTN gateway and the above usage:​

New-CsOnlineVoiceRoute -Identity "Route1" -NumberPattern "^\+(\d{4})|^(\d{4})" -OnlinePstnGatewayList pbx.company.com -Priority 1 -OnlinePstnUsages "Usage1"

As you can see the command creates a route “Route1” where TEAMS will pass the call to PSTN gateway pbx.company.com (a domain in Vodia PBX) if the dialed number has at least 4 numbers (that is of course based on our example here where we want to give each user a 4 digit extension, but it is up to your setup), with or without a + sign. That way, you could dial a 4 digit extension or an E.164 number with country code and + sign.

Of course, multiple routes can be created with different priorities.

To find out different routes, use:

Get-CsOnlineVoiceRoute

Let’s create a voice policy using the same usage to which our PSTN gateway is linked above:​

New-CsOnlineVoiceRoutingPolicy "Policy1" -OnlinePstnUsages "Usage1"

The result for the example:

Identity         : Tag:Policy1
OnlinePstnUsages : {Usage1}
Description      :
RouteType        : BYOT

You can, of course, create a policy with several PSTN Usages, but we will keep it simple and to the point regarding our example.

Let’s grant our user John Smith our voice policy:​

Grant-CsOnlineVoiceRoutingPolicy -Identity "js@company.com" -PolicyName "Policy1"

You can check the policy assignment with this command:

Get-CsOnlineUser "js@company.com" | select OnlineVoiceRoutingPolicy

Now the outbound dialing policy and routing is complete and John Smith can call out. In this example, that outbound call will end up in your Vodia PBX domain pbx.company.com.

In our example, we could set up your domain in Vodia PBX (explained in Vodia PBX section) so that:

  • If that extension (4 digits in this case) exists in your Vodia PBX domain and registered, it will be called from your Teams user whether its a SIP desktop phone registered to your Vodia domain, Vodia desktop app, Vodia web app or Vodia smartphone app.

  • If that extension does not exist (say an E.164 10 digit number etc.), then Vodia will route the call to a PSTN gateway or SIP trunk so that call can go out.

Last updated on