Skip to main content

​
Answer anyone’s ringing call and move live calls between phones

Two inbound-portability workflows cover the “the call is ringing/somewhere else” problems a softphone-only setup can’t solve:
  • Call pickup — answer a call that is ringing on a colleague’s extension, from your own device. Directed pickup lets you name the extension (“answer whatever is ringing on 201”); group pickup takes the longest-ringing call in your pickup group without naming a target.
  • Call flip — move a call you already answered from one of your registered devices to another (desk phone → mobile, or back), while the caller stays on the line.
Both work on any SIP device registered to your Orbit account — desk phones (Yealink, Grandstream, Polycom) and softphones (the Orbit dashboard softphone, mobile app, Linphone, Bria, Zoiper) behave identically.
Pickup and flip only ever re-target a live leg to another device on your own tenant. Neither feature originates a new external call — the actual phone call still exits through the same wholesale route it arrived on.

​
Pick a workflow

​
Ringing-legs index (how pickup knows what’s ringing)

Pickup needs a live view of which inbound calls are ringing and on which extension. Orbit keeps this in a sub-30-second ringing-legs index:
  • When an inbound call starts ringing on an extension, the voice webhook registers it; when the caller hangs up or someone answers, the webhook clears it. These register/clear hooks are internal system-to-system calls, authenticated with the internal service token — you don’t call or configure them directly.
  • The GET /api/v1/voice/pickup pickup tray lists the current ringing calls oldest-first, so dashboards and softphone UIs can render a “calls you can pick up” panel.
Each entry reports the target extension, the caller’s number and name, and how long it has been ringing:
An outdated tray entry simply loses the races below — pickup claims are atomic, so a stale row can never cause a double answer.

​
Directed pickup — answer a specific extension’s ringing call

Directed pickup is the dashboard/API equivalent of dialling **201 (“answer whatever is ringing on extension 201”) on a traditional PBX:
  • targetExtension — the extension (or SIP username) the ringing call is aiming at.
  • pickingUpDeviceUsername — your device’s SIP username (from your list of SIP credentials). The call is bridged to that device.
On success you get the resolved call plus the bridge instruction:
If nothing is ringing on the named extension, the request returns 404 (“no call ringing on that extension”). If two colleagues go for the same call at the same moment, exactly one wins — the loser gets a 409 and the call is never bridged twice.

​
Group pickup — grab the oldest ringing call in your group

Group pickup is the equivalent of dialling *8 — “answer the longest-ringing call in my pickup group,” no target needed:
  • With no groupMembers, your pickup group is the whole tenant — the classic *8 “grab any ringing call” behaviour.
  • Pass groupMembers (an array of extension/SIP usernames) to restrict the pool to a named team’s ringing calls:
The response shape matches directed pickup, with pickupType: "group".
Every successful pickup writes an audit-log entry with the picking user, the resolved call, and the target extension — so “who took that call?” is answerable after the fact.

​
Call flip — move a live call between your own devices

Call flip handles the commute/meeting problem: you’re on a live PSTN call on your desk phone, and you want to keep talking from your mobile (works in the other direction too).

​
1. Push — issue a handoff from the current device

  • callSid — the live call you’re flipping. The dashboard’s active-call view carries it; it’s also in the pickup response when you took the call.
  • targetDeviceUsername (optional) — pin the handoff to one device so only that SIP username can pull it, or omit it so any of your registered devices can pull.
  • The remote-party fields (optional) make the dashboard’s pending-flips list easier to scan.
The response hands back a token (full secret), a 4-digit shortCode for desk-phone dialling, and an expiresAt; unused handoffs expire after two minutes:
Re-pushing a flip for a call you already flipped returns the existing handoff instead of stacking duplicates.

​
2. Pull — claim the handoff from the other device

From the second device (pressing “Pull call” in the dashboard or mobile app):
  • token — the full token from the push, or the 4-digit short code on the dial path.
  • pulledByDeviceUsername — the SIP username of the device doing the pull; if the push pinned a target device, it must match.
The pull resolves the live call so your client can signal the bridge and release the first device.

​
Legacy desk phones — *7 plus the short code

Phones with no dashboard access dial *7 then the 4-digit shortCode (for example, *7 4239#); the voice platform claims the handoff on that phone’s registered identity. The claim is validated with the same expiry/competition rules as the API pull.

​
Expiry and racing

Pulling an expired handoff returns 410 with expiredAt; pulling one another device already claimed returns 410 with which device won, so you can tell which phone took the call. A handoff belongs to your tenant — the token alone grants nothing to anyone outside it.

​
Track and cancel

GET /api/v1/voice/call-flip lists your pending flips (for the dashboard’s pending list), and a push can be withdrawn before a pull with:

​
Prerequisites and scope

  • Devices: the picking-up or pulling device must be a registered SIP device under your tenant (Voice → SIP credentials in the dashboard). Any standards-compliant SIP endpoint works — desk phone or softphone.
  • Roles: pickup and flip endpoints require one of the workspace owner, admin, developer, or agent roles. The internal ringing-index and dial-code hooks are platform internals and not part of the customer API.
  • Inbound only: pickup re-targets a pre-answer inbound leg; it never originates a new external call and never hands a call to an outside number. Call flip likewise moves the call only between your own registered devices. For anything else — an external party, a colleague on an outside line — use transfer instead.