Skip to main content

​
Link a SIP extension to a user

Set the Linked user field on a SIP credential and inbound calls to that extension fire a native incoming-call push directly to that user’s phone — the PushKit path on iOS or a high-priority FCM payload on Android. The push wakes the OS-level incoming-call UI even when the app is locked or force-quit, something the organization-wide ring alert cannot guarantee. It is additive, not a replacement: the existing tenant-wide alert still fires on every inbound ring, and the per-user push lands on top of it. You use the per-user link when a specific phone must ring natively. Edit the extension. In the dashboard open Voice → Extensions, click the credential, and set Linked user on it. Over the API send userId on the credential’s create or update request:
The link targets any user in your organization, and the check runs server-side: a userId that is not a live member of this organization is rejected with 403 FORBIDDEN, so a link never rings a stranger’s phone. Re-setting userId on a PATCH requires the same membership check; clearing it (userId: null) is always allowed and returns the credential to the alert-only behaviour. To unlink, send userId: null:

​
2. Register the user’s VoIP token

A linked user only rings if that user has a row in the VoIP devices registry — this is a separate table from the alert-push device tokens and it carries the PushKit / high-priority-FCM call token. Have the target user register from their device:
Call it from the SDK’s token-refresh callback — it is an idempotent upsert on the token string, so re-registration refreshes without duplicating. On Android pass the FCM registration token; the call push then ships at FCM priority: high with a call-only payload. Detail: Push device tokens and scheduled sends.

​
3. Ring a linked extension

Route an inbound number to the extension’s SIP username — a ring group, softphone-register route, or an IVR dial verb. On each inbound ring Orbit resolves the surviving (non-DND) SIP usernames on the route, looks up their linked users, and fires one per-user Call push per distinct user, in addition to the tenant-wide alert. Disabled or deleted credentials are excluded from the lookup, so a disabled device never rings the user’s phone. The resolution log on each ring confirms both surfaces fired:
voipPushedUsers reports how many distinct linked users the ring pushed — 0 means the tenant-wide alert still fired but no linked user was in the destination set (or none had a VoIP token).

​
4. Behaviour contract

​
5. Guardrails

  • Membership-checked on write. The linked user must be a live member of your organization; the check runs on both create and update, and a rejected userId surfaces as 403 FORBIDDEN. Clearing (null) is always permitted.
  • The ring never blocks. Per-user push resolution and send are fail-open end to end — a lookup or send error degrades to “tenant-wide alert only” for that ring instead of surfacing into the ring path. The per-user push send is documented as never-throw.
  • The tenant-wide alert always fires. The linked user is additive — alert recipients who are not the linked user continue to receive the organization’s ring alert exactly as before.

​
6. Troubleshooting