Teams presence and click-to-call
Part 2 and 3 of the Teams link (part 1 is Direct Routing, teams-direct-routing.md).
Code: pbx/crates/integrations/src/teams/ (connector key teams), app package integrations/teams/.
Presence, both ways
| Teams (Graph availability / activity) | Extension status |
|---|---|
| Available, AvailableIdle | available |
| Busy, BusyIdle, InACall, InAConferenceCall, InAMeeting | busy |
| DoNotDisturb, Presenting | dnd |
| Away, BeRightBack | away |
| Offline, PresenceUnknown | offline |
The extension to Teams uses setPresence (session id = the app's client id, one hour, renewed on the next change);
offline calls clearPresence, so Teams shows the user's own state again.
Loop safety. Both systems report what we wrote. A change equal to the last synchronised state and coming from the
other side within the echo window is dropped (Echo), a repeat is Unchanged, and a call in progress on the PBX
always wins: a Teams change that is not busy is ignored (CallWins) while the extension is on a call.
Notifications. One Graph subscription per 600 linked users (/communications/presences?$filter=id in (...),
changeType: updated). Presence subscriptions live at most one hour: the planner renews when 20 minutes are left,
recreates an expired or lost one (a renewal answered 404 falls back to a create) and deletes one whose user left.
reauthorizationRequired, subscriptionRemoved and missed lifecycle events are parsed so the host acts on them.
Every notification carries the shared client_state; a post without it is refused whole.
Entra app registration (owner work)
Application permissions Presence.Read.All, Presence.ReadWrite.All and User.Read.All with admin consent, a
client secret, and the public https notification address. Secrets (client_secret, client_state) are sealed
write-only in the install. All Graph calls go through the guarded outbound client.
Click-to-call from Teams
integrations/teams/manifest.json is a Teams app (manifest 1.17) with a personal Phone tab served by the PBX at
/integrations/teams/tab. Replace {{PBX_HOST}} with the PBX host, zip the manifest with color.png and
outline.png, and upload it (or publish it to the organisation catalogue). The tab calls
POST /api/v1/calls/click-to-call (click-to-call.md) as the signed-in user: the user's phone
rings first, the number is dialled when they answer, with their own calling permissions and toll-fraud limits.
The test teams_app_manifest_is_valid checks the manifest.
The tab (). The PBX serves it itself: GET /integrations/teams/tab (the page),
/integrations/teams/tab/end (the OAuth redirect inside the sign-in popup) and the two scripts under
/integrations/teams/tab/, with their own Content Security Policy (the web client's forbids framing; this one
allows frame-ancestors only for the Teams and Microsoft 365 hosts and loads the Teams JS SDK from
res.cdn.office.net). Setup: register a public OAuth client with POST /oauth/register whose only redirect URI is
https://<PBX_HOST>/integrations/teams/tab/end, and put its id in the manifest as {{MPBX_CLIENT_ID}} (it is
the client_id query of the tab's contentUrl). On first use the tab shows Sign in to MonoPbx: the Teams SDK
(authentication.authenticate) opens the PBX's consent page in a popup (authorization code with PKCE S256, scope
self:read only), the popup's redirect hands code and state back to the tab, and the tab exchanges the code at
/oauth/token with its verifier. The token stays in the tab's memory (never in a cookie or storage); when it
expires, or the PBX answers 401, the sign-in button comes back. Errors are shown with the fixed messages of the Jira
app. Source and tests: pbx/bin/mpbx/assets/teams_tab/ and cd integrations/teams && npm test (node, against a
fake PBX). Still to confirm in a Microsoft 365 tenant: the popup flow and the CDN SDK version.
AI tools
int_teams_get_presence and int_teams_set_presence (offered only when the install's allow-list names them).