Microsoft 3CX Teams Integration Configuration Troubleshooting

What 3CX license do I need?

3CX Enterprise Edition.

I'm currently using another product to connect my 3CX to Teams, how do I clear the old configuration?

If you are currently using other services to connect Teams to 3CX, wipe them out and bring the direct routing config back to default. This will drastically help to avoid errors in your configuration and allow clean assignment of users.

1. Revert Teams users’ policies back to the default “Global (Org-wide default)”. This is commonly set for: Calling policy, Dial plan and Voice routing policy.
2. Clean up existing dial plans by calling Get-CsTenantDialPlan and then remove all where the “Identity” is not “Global” with Remove-CsTenantDialPlan.
3. Repeat the same for “get-CsOnlineVoiceRoutingPolicy”, “Get-CsOnlineVoiceRoute”, “Get-CsOnlinePstnUsage” and “get-CsOnlinePSTNGateway” to find and remove unnecessary configuration.

When I run the 3CX scripts, I'm getting an error saying ‘The term ‘set-XYZ is not recognized’

This can result from two common sources

• If you don’t run the scripts via an elevated PowerShell prompt, which then fails to install the necessary PowerShell Teams module.
• If you have already installed the PowerShell module for Skype for Business or Teams, but they are outdated.

Check the version by running Get-InstalledModule in PowerShell.

2.3.1 or higher is expected.

If you don’t see an installed version, or on an older version is displayed, run

Install-Module -Name MicrosoftTeams -Force

from an elevated PowerShell, terminal to install/update to the latest version.

When I run the 2nd 3CX script (User Script), I get an error saying ‘Cannot modify the parameter: “OnPremLineURI” because it is restricted for the user service plan’

This is a strong indicator that the user is not licensed, not yet provisioned by Microsoft or you have a calling plan enabled on the user.

Case 1: Microsoft 365 Phone System

First, log in to https://admin.microsoft.com/#/users and check if the “Microsoft 365 Phone System” addon was assigned to the user. Without this, you cannot proceed.

If the license shown above was just assigned, it can take up to 24 hours until the core of Teams will see the same license. There is nothing you can do to speed this process up. However, you can check to see if it is ready. Log in to https://admin.teams.microsoft.com/users and check the column “Phone System”.

For the user in question, it needs to state On to be connected to 3CX. If this is not the case, there is no need to proceed with any call tests or other actions.

Case 2: Microsoft 365 Business Voice

In case you opted for the “Business Voice” addon instead of the cheaper “Phone System” addon, ensure you uncheck “Microsoft 365 Domestic Calling Plan” within the admin portal of Microsoft for the user(s) in question.

After generating the 2nd 3CX script (User Script), my user list appears empty

You may receive the following error

or has missing users from it.

This commonly has three reasons:

• The user is not licensed by Microsoft.
• The user is not provisioned yet by Microsoft.

• You have not assigned an office phone number in e164 format to the user in the admin portal. The office phone number shall generally be the outbound caller ID of the user which can then also be synchronized to 3CX for less administrative overhead. Login to https://admin.microsoft.com/#/users and open the user in question to validate the “Office phone” number.

What DNS Records do I need to update?

Your chosen FQDN will be used by Microsoft to route traffic to your 3CX to place outbound calls. Therefore it must point to the static public IPv4 address of your 3CX installation.

For example, assume your email address domain is xyz@marketing-3cx.com. Then create an A record DNS entry in your DNS server for teams.marketing-3cx.com. Point this A record to your 3CX public IP address. You cannot do this for domains you don’t own, such as onmicrosoft.com or any 3CX provided domain as you don’t control the DNS server of this domain. AAAA records are not needed as Teams does not support IPv6.

Note: In this example, teams.marketing-3cx.com was used but it can be anything you would like it to be as long as it is within marketing-3cx.com.

Which provider can I purchase my SSL certificate from?

Microsoft has stipulated that the issuer of the certificate must be any of the ones outlined here.

We have tested and documented using SSL.com so unless you have a really good reason to choose another provider and are ready to do your own troubleshooting, use SSL.COM.

Can I use my existing or a new Wildcard SSL Certificate?

You cannot use wildcards for Secure SIP and this is also a reason to not connect Microsoft 365 Teams.

What does my SSL Certificate need to cover?

The certificate must cover exactly the domain you have specified. For example, if your domain is xyz.com, you must use teams.xyz.com.

My Certificate has not been provided including the Intermediate Certificates, what do I do?

If your issuer doesn’t give you a single ready file with the Certificate plus the Intermediate Certificates and you need to make yourself, do this:

1. Create a new file and call it “teams_cert.pem” and open it with Notepad.
2. At the top of the file, paste the contents of the Certificate file from your Provider (must be first).
3. Below it, paste the Intermediate certificates your provider gave you.
4. Save the file and use this one as your Certificate file.
   

According to Microsoft, the issuer of the certificate must be any of the ones outlined here.

My 3CX is using a Custom Domain, what additional steps are needed?

In this case, you have to configure the secure SIP section within your 3CX System. You have to do this also if you are not using the same custom domain FQDN for your Teams configuration. The section must be filled for 3CX to start its TLS listening interface. Therefore a valid certificate and key pair must be entered in this section!

Ensure that in the certificate itself you include all intermediate certificates provided as a certificate bundle by the issuing root authority.

Why is my Team's SBC showing “Trunk Down”?

After you run the first script (Dial Plan Script), the connection is created between Teams and 3CX. When you first run the script, for a short while the connectivity and SIP Options might be shown to be Inactive and with a Warning. This is to be expected. After 15 minutes, however, this should change.

In case it does not, ensure you have opened the correct SIP port and review the sections above for DNS Records and SSL Certificate as those commonly cause this state. Logging in Teams is sparse, the best check you can do would be to navigate to https://admin.teams.microsoft.com/direct-routing/v2, click on the SBC connected to 3CX, scroll down and check if anything of interest is shown here:

Note: The “Network effectiveness” counter in the SBC section might show red but is not an issue. This is a calculation of the calls flowing through the system. In the beginning, you will most likely run small test calls, which are seen as an issue by Teams (too short, too frequent, etc). On production usage, this will stabilise and is nothing to worry about.

Why are my Outbound Calls failing?

Call from Teams to 3CX might fail. While analysing the logs via BinLog Viewer the log entry

can be found. This indicates that the user in Teams has recently changed the “Office Phone” number and is not synchronized yet to 3CX or the extension was deleted in 3CX.

Why does my Teams client not work immediately?

As strange as it may sound but after you run the scripts, your Teams client does not immediately update to the latest settings. As you can see below, under the dial pad, the user should see the information regarding their office number, which is a combination of the “Office phone” number set in the admin portal of Microsoft and the extension number of the user in 3CX.

Unless this is displayed to the user, calls will fail. Therefore restart the Teams client regularly. Upon restart, the client will reprovision its configuration.

How do I disable Teams Voicemail?

Teams default handling of unanswered calls is to send them to the users’ voicemail in Teams. However, this also applies if the Team client is closed. In this case, all calls are immediately connected to the user’s Teams voicemail interrupting ongoing call flows at this moment. Therefore it is advised to let 3CX handle the voicemail and call flows.

Set “If unanswered” with the “Do nothing” setting from the Teams client for each user.

My Teams Room cannot be integrated

Usually when Teams Rooms are created, they appear in Azure AD with a Display Name, but no First and Last Name.

What you need to do is:

1. Populate the First and Last Name fields in Azure AD
2. From the 3CX Management Console → Settings → Microsoft 365 → User Sync, find this user and sync them with 3CX so that a new Extension is created
3. From 3CX Management Console → Settings → Microsoft 365 → Teams Direct Routing, generate the User Script again, ensure that the email of the user is present and run it again.

Note: Teams Rooms must also have the “Microsoft 365 Phone System” addon.

Only one App on my iOS device rings

If you have the 3CX and Teams APP installed on an iOS device, you will notice that only one of both apps will ring on incoming calls. This results from a limitation in iOS to render two calls, from the same caller ID, via Apple’s CallKit. CallKit is the interface used when answering regular GSM calls from the lock screen. We recommend the use of the 3CX App for calls as it offers more functionality in this segment.

My SIP carrier needs the FROM and TO number format changed

The SIP FROM header is taken from the extension setting in 3CX when placing a call to the PSTN network. The TO header number is formatted in e164 when the outbound call inbounds from Teams to 3CX. You may need to adjust your outbound rules to cater for numbers starting with a + or in case your SIP provider does not support dialling in e164 format, trim the number to a format known to your provider.

It is advisable to disable the e164 number processing in 3CX to have transparent management of the TO number in the outbound rules when combined with Microsoft Teams.

What are the exact rules I need to set on my firewall?

In case your network defines strict in-/outbound connection via the corporate firewall, you must allow the following connectivity from the 3CX host:

Inbound (from Teams to 3CX)

Outbound (from 3CX to Teams)

*Depending on configuration of 3CX.

Is Microsoft DoD and GCC high environment supported?

Both additional services are not supported for 3CX’s direct routing at the moment.

My outbound calls are blocked, how can I fix it?

There is an additional setting in Microsoft 365 Teams which can be set to prevent users making outbound calls.

Option 1

Navigate to https://admin.teams.microsoft.com/users and inspect the assigned policies for the user. Look for “Calling policy” and ensure it is set to “3CX Calling Policy” (default setting).

Option 2

Navigate to https://admin.teams.microsoft.com/users and inspect the “Voice” outbound calling allowance. Set this to “Any destination”.

Last Updated

This document was last updated on 27 October 2022

https://www.3cx.com/docs/microsoft-teams-integration-faqs/