​

Set up the browser (WebRTC) softphone

1. The built-in dashboard softphone — Orbit ships a ready-made softphone inside the dashboard. This is the zero-code path and the right starting point for most teams.
2. An embedded LiveKit-based softphone (Softphone in @devotel/orbit-web-sdk) — you mount the softphone inside your own agent workspace (CRM, contact-centre wall, internal tool) with your own UI.
3. An embedded SIP-over-WSS softphone (the SIP-register path) — a classic SIP client (e.g. JsSIP) that registers straight against Orbit’s WebRTC-to-SIP gateway, for teams that want standard SIP semantics and their own call-control logic.

​

1. Device registration & VoIP push tokens (mobile)

curl -X POST https://api.orbit.devotel.io/api/v1/push/voip-devices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "ios",
    "voip_token": "APNS_VOIP_TOKEN_HEX",
    "bundle_id": "com.yourcompany.orbit-agent"
  }'

• platform is ios or android. On iOS voip_token is the PushKit (CallKit) token; on Android it’s the FCM registration token used for the high-priority call channel.
• bundle_id (iOS only) is the app bundle id — the VoIP push topic is <bundle_id>.voip.
• The response returns the registered device (id, platform, last_seen_at).

​

2. Mint softphone credentials

​

Built-in dashboard / embedded LiveKit softphone

curl -X POST https://api.orbit.devotel.io/api/v1/voice/softphone/token \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": {
    "token": "<livekit access token>",
    "media_url": "wss://..."
  }
}

​

Embedded SIP/WSS softphone

curl -X POST https://api.orbit.devotel.io/api/v1/voice/softphone/register \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "callerIdNumber": "+15559876", "deviceLabel": "agent-desk-04" }'

{
  "data": {
    "sipUsername": "u_agent_x1a2b3",
    "sipPassword": "...",
    "sipDomain": "sip.orbit.devotel.io",
    "wssUrl": "wss://...",
    "iceServers": [{ "urls": "stun:..." }],
    "callerIdNumber": "+15559876",
    "expiresAt": 1716110400000
  }
}

• Credentials live for 60 minutes — re-register before expiresAt or the session drops.
• callerIdNumber must be a number your organization owns (it’s 403’d otherwise) — this is how outbound CLI spoofing is blocked.
• The username binds to your organization, so a stolen username can’t be replayed against a different tenant.
• Token issuance is owner/admin/developer-scoped — it’s not a public, anonymous endpoint.

​

3. Choose how inbound calls reach the softphone

• DNIS → queue → softphone. The most common path: your phone number’s inbound routing sends the call to an ACD queue, and the queue offers it to an available agent’s browser softphone (and, if they’re on the mobile app, a VoIP push — section 1). You set this up per number in the dashboard’s number routing, or through the flows builder.
• DNIS → SIP routing. Route inbound calls to the SIP domain your softphone registrations live on. Use this when your inbound traffic already lands on SIP (for example a DID forwarded to your SIP URI) and you want the registered softphone to answer directly.
• The caller’s softphone dials out. For outbound-driven teams the inbound question never arises — the agent initiates calls and any inbound answer is on a number that routes to a queue (back to option one).

​

4. Full JS snippet — mic, VoIP push + browser fallback

import { OrbitSoftphone } from "@devotel/orbit-web-sdk";

const softphone = new OrbitSoftphone({
  apiBaseUrl: "https://api.orbit.devotel.io",
  apiKey: "YOUR_API_KEY", // serve from your backend — never commit it
  // Optional: force a media URL. Omit to use the token response.
  // mediaUrl: "wss://...",
  onCallStateChange: (s) => console.log("softphone state:", s),
  onError: (e) => handleSoftphoneFailure(e), // ← fallback lives here
});

// 1. Mic is gated on the browser's getUserMedia. Ask for it on a user
//    gesture (a click) — not page load — so the permission prompt is
//    attributed and the mic isn't held open on an idle tab.
async function armMicrophone() {
  await navigator.mediaDevices.getUserMedia({ audio: true });
  await softphone.connect(); // mints token + publishes mic
}

// 2. Place an outbound call.
async function callCustomer(e164) {
  return softphone.dial(e164); // returns call_id when ringing
}

// 3. Fallback: if the browser/media path can't connect, hand the call
//    to a click-to-call bridge (the caller's desk phone or mobile
//    rings, and the agent talks there). This is also the path when an
//    enterprise network blocks WebRTC entirely.
function handleSoftphoneFailure(err) {
  console.warn("WebRTC unavailable, falling back:", err.message);
  // show "call me on my device" UI → POST /voice/click-to-call instead
}

// VoIP push (mobile only): the browser cannot receive a VoIP push -
// mobile handles it natively. From the browser, the inbound ring just
// arrives when an inbound call is routed to the agent's room.

​

5. Verification & troubleshooting

1. Mint a credential (section 2), connect the client (section 4), and look for a room connect / SIP registered event.
2. Place an outbound call to your own mobile — you should hear ring, then two-way audio on answer.
3. Have an inbound call routed to your number (section 3) and confirm the softphone rings and answers.
4. If you registered a mobile VoIP device (section 1), background the mobile app and confirm a native incoming-call UI appears.

​

Where to go next

• SIP trunk setup — if you want to bring your own carrier/trunk alongside the browser softphone.
• Voice queues — the ACD queue inbound calls route through before a softphone answers.
• Web SDK — full event map for Softphone and the other SDK surfaces.