Onyx VoiceDocumentation
All chapters

Docs / Phone system

Microsoft Teams

Onyx Voice can be the Session Border Controller (SBC) for a company's Microsoft Teams, using Microsoft's Direct Routing. Calls to a person's extension then also ring them in Teams, and people call out and call colleagues from Teams as their extension, with the company's numbers, routes, call limits and recording. This chapter covers what Microsoft needs, connecting a tenant, giving people their Teams number, the Microsoft 365 side, and what to check when it does not work.

Onyx Voice is not on Microsoft's list of certified SBCs. It speaks Direct Routing the way Microsoft documents it, but Microsoft support may decline problems that involve it.

What Microsoft needs

  • Teams Phone licences. Every person who makes or takes calls in Teams needs Teams Phone (Teams Phone Standard, or a plan that includes it such as Microsoft 365 E5).
  • An SBC name in the company's own domain. For example teams.acme.com. The domain (here acme.com) must be verified in the company's Microsoft 365, and at least one licensed user must sign in with a name in that domain: Microsoft only activates the domain for Direct Routing then, which can take a day. Names ending in .onmicrosoft.com are not accepted.
  • Public DNS and a certificate. The name needs a public A record pointing at this server's public address, and the server's certificate must carry it. With Let's Encrypt on (see Names and certificates), Onyx Voice adds the name to its certificate by itself once the DNS record is there; port 80 must reach the server for that. The certificate has an RSA key, which Microsoft needs.
  • Ports. Microsoft connects to the connection's TCP port (TLS) shown on the page, from its own addresses only. Calls' audio (SRTP) uses the server's usual RTP port range (UDP). Forward both from Microsoft's addresses: for Microsoft 365 52.112.0.0/14 and 52.120.0.0/14. On a server installed from the Onyx Voice image, Onyx Voice opens the TLS port in its own firewall for those addresses.

Connecting a tenant

Only a system administrator can connect a tenant, because it opens a port and puts a name on the server's certificate.

  1. Pick the company at the top of the console and open Microsoft Teams (under Connections).
  2. In Connect Microsoft Teams, enter the SBC name (for example teams.acme.com), choose the Microsoft cloud (Microsoft 365 (worldwide, GCC), GCC High or DoD) and, if you want a limit, Calls at once.
  3. Click Connect.

Onyx Voice gives the connection its own TLS port (the first free one from 5067), restarts the phone engine when no calls are up so it listens there, and starts sending Microsoft its regular SIP OPTIONS pings. The card then shows:

  • whether Microsoft answers (Microsoft answers with the round-trip time, or Waiting for Microsoft);
  • whether the certificate names the SBC name and is from a public authority with an RSA key;
  • whether the name points at this server in DNS;
  • the port Microsoft connects to.

Switch off stops the connection without forgetting it; Remove forgets it and closes its port.

From the command line: onyx teams set acme --fqdn teams.acme.com (--cloud gcch, --max-calls 24, --enabled off), onyx teams show acme, onyx teams delete acme.

Giving people their Teams number

Each person who uses Teams needs a phone number in Teams (assigned in Microsoft 365, see below). Enter the same number on their extension, so Onyx Voice knows who is calling:

  1. On Microsoft Teams, in Teams numbers, type the person's number as + and the full number, for example +1 612 555 0101.
  2. Leave Ring in Teams ticked to ring their Teams together with their phones; untick it if they only call out from Teams.
  3. Click Save.

A tenant administrator can do this too. From the command line: onyx teams user acme 101 +16125550101 (--ring off, or none instead of the number to remove it).

What happens then:

  • Calls to the extension ring the person's phones, their apps and Teams at the same time; whichever answers first takes the call. Do not disturb, forwarding and voicemail work as before.
  • Calls from Teams come in as the person's extension: they dial colleagues by extension and outside numbers as from their desk phone, with their outside caller ID, the company's outbound routes and call limits, and their recording setting. A call from a Teams number that no extension has is refused.
  • Transfers made in Teams go where a colleague dialling the same number would go.

The Microsoft 365 side

The Microsoft 365 side card lists the steps and gives the Teams PowerShell to copy (Copy PowerShell), with the SBC name, port and every person's number filled in. A Teams administrator of the company runs it once, and the last two lines again for each new Teams user. From the command line: onyx teams script acme.

It does this:

  1. New-CsOnlinePstnGateway: Onyx Voice as the SBC, with its port.
  2. A PSTN usage, a voice route for every number through Onyx Voice, and a voice routing policy, all named "Onyx Voice".
  3. For each person: Set-CsPhoneNumberAssignment (their Teams number, type DirectRouting) and Grant-CsOnlineVoiceRoutingPolicy. The script uses the extension's e-mail as their sign-in name; check it.

Microsoft can take up to an hour to start using a new SBC.

When it does not work

  • Waiting for Microsoft stays, or Microsoft shows unreachable. Microsoft is not answering Onyx Voice's pings. Check the certificate and DNS lines on the card, that New-CsOnlinePstnGateway was run with the same name and port, and that the domain is active (a licensed user signs in with it). Outbound TCP 5061 to Microsoft must be open.
  • Teams users cannot call out. Check that their number on the extension is exactly the one assigned in Teams, and that the voice routing policy was granted to them. The engine log names a refused number ("Teams call from ... refused").
  • Calls ring Teams but there is no sound. The RTP port range (UDP) is not forwarded from Microsoft's addresses, or the server's public address (Server settings, Calls and network) is wrong.
  • Calls do not ring Teams. Ring in Teams is off for the person, or the connection is switched off.