Skip to main content

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, AvailableIdleavailable
Busy, BusyIdle, InACall, InAConferenceCall, InAMeetingbusy
DoNotDisturb, Presentingdnd
Away, BeRightBackaway
Offline, PresenceUnknownoffline

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).