Skip to navigation

Browser softphone

Put the rep’s phone in your web app with @rydhm/web. Online status, outbound calls, callbacks that ring in the browser, mute and hang up.

The softphone is the rep’s side of a rep call. It’s headless: @rydhm/web handles the audio, the connection and the events, and your app draws the buttons. It runs in current Chrome, Edge, Firefox and Safari, desktop and mobile.

npm install @rydhm/web

Without a build step, the script tag gives you the same class as window.Rydhm.Softphone (no data-key needed for the softphone alone):

<script src="https://staging.rydhm.ai/engine.js"></script>
<script>
const phone = new Rydhm.Softphone({ token, apiUrl: "https://api-staging.rydhm.ai" });
</script>

engine.js is a small loader; when the softphone goes online it loads engine-livekit.js from the same directory. A Content Security Policy must allow both files: see Browser support, size and CSP. With npm, livekit-client is a chunk your bundler splits out instead.

1. Mint a token on your server

The softphone needs a token for one rep, from your server (it takes your secret key). It’s valid for 12 hours.

server.ts
import express from "express";
import { Rydhm } from "@rydhm/sdk";
const rydhm = new Rydhm(); // RYDHM_API_KEY with calls:write
const app = express();
app.post("/api/softphone-token", async (req, res) => {
const rep = await currentUser(req); // your auth
await rydhm.reps.upsert(rep.id, { name: rep.name });
res.json(await rydhm.reps.softphoneToken(rep.id)); // { url, token, presenceRoom, expiresAt }
});

2. Go online in the browser

import { Softphone } from "@rydhm/web";
const getToken = () => fetch("/api/softphone-token", { method: "POST" }).then((r) => r.json());
const phone = new Softphone({
token: await getToken(),
refreshToken: getToken, // called when the token has expired, so the rep stays online all day
apiUrl: "https://api.rydhm.ai",
});
phone.on("state", (s) => ui.status(s.presence, s.call, s.muted)); // presence: offline | connecting | online
phone.on("error", (e) => ui.toast(e.message, e.fix));

The softphone connects right away (pass autoConnect: false to wait for phone.connect()). Being connected is being online: Rydhm marks the rep online and rings their callbacks here. It reconnects by itself with backoff, refreshing the token when it expired. phone.disconnect() goes offline.

3. Make a call

Your server starts the call (rydhm.repCalls.create) and hands its reply to the browser, which joins it:

async function dial(to: string) {
const call = await fetch("/api/calls", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ to }),
}).then((r) => r.json()); // { id, status, join: { url, token } }
await phone.join(call); // joins the call's room and publishes the microphone
}
phone.on("answered", (a) => ui.answeredBy(a.by)); // human | machine | screening
phone.on("transcript", (t) => ui.line(t.id, t.speaker, t.text, t.final)); // speaker: rep | prospect | ai
phone.on("suggestion", (s) => ui.suggest(s.text));
phone.on("timer", (t) => ui.timer(t.seconds));
phone.on("voicemail", (v) => ui.voicemail(v.kind, v.text)); // detected | beep | left
phone.on("ended", (e) => ui.ended(e.outcome, e.durationSec));
muteButton.onclick = () => phone.mute(!phone.state.muted);
hangupButton.onclick = () => phone.hangup();

The microphone is asked for on the first join: call it from a click. Join straight away: a call’s join token is valid for 15 minutes, a callback’s for 2. To hand a call to the AI for the voicemail, have your server call leaveVoicemail (a button in your UI that posts to your server): the rep is released at once and can dial the next one. See AI voicemail.

4. Take callbacks

When a prospect calls back one of your pool numbers, it rings the rep’s browser first:

phone.on("incoming", (call) => {
ui.ring({
from: call.from,
ref: call.externalRef, // the call they're calling back about, when known
seconds: call.ringSeconds,
answer: () => call.answer(), // joins the call with the microphone
decline: () => call.decline(), // routing moves on: their mobile, then voicemail
});
});

phone.incoming lists the calls ringing now; phone.answer() and phone.decline() act on the newest. A callback that isn’t answered within ringSeconds stops ringing here and moves to the next step of the routing.

Members

MemberWhat it does
new Softphone({ token, refreshToken?, url?, apiUrl?, inputDeviceId?, outputDeviceId?, autoConnect?, debug? })token is your server’s softphone-token reply (or its token string with url).
connect(), disconnect()Go online, or offline.
join(call)Join a call: the POST /v1/rep-calls reply ({ id, join }) or { url, token, callId? }. Publishes the mic.
answer(callId?), decline(callId?, { notify? })A ringing callback (the newest when no id). decline(id, { notify: false }) only stops it ringing here, when your server already declined it or another tab took it.
hangup({ notify? })Ends the call for everyone, then leaves the room. Rejects when Rydhm couldn’t be told (the other side may still be on the call). hangup({ notify: false }) only leaves the call in this browser, when your server already ended it.
mute(on = true), setInputDevice(id), Softphone.inputDevices()Microphone control.
setOutputDevice(id), Softphone.outputDevices()Speaker picker, where the browser allows it (Chrome and Edge; Safari lists none).
state{ presence, call, callId?, muted, quality, startedAt?, durationSec }. call is idle, ringing, joining or in_call.
duration, incoming, levels()Seconds in the call, ringing calls, audio levels 0 to 1 for a meter.
on(event, cb)state, incoming, ringing (from: the caller ID the prospect sees, to), answered, screening (a call-screening assistant answered: the rep says who they are), transcript, suggestion, voicemail (kind: detected | beep | left), ended, timer, event (every raw event, like call.voicemail_failed), error. Returns the unsubscribe function.
destroy()Leave everything. It doesn’t hang up the call for the prospect.

How it works

  • The softphone token joins the rep’s presence room, rep_presence_<rep id>, with permission to listen and receive data only, and no AI in it. Being in that room is being online.
  • A callback arrives there as a call.incoming event on the rydhm.events data topic, with data.join, a short-lived token for the call’s own room, and data.ringSeconds. Answering is joining that room and publishing the microphone.
  • In a call, the call.* events arrive on the same topic, so the transcript and suggestions reach the browser directly.
  • Decline and hang up call POST /v1/rep-calls/{id}/decline and /hangup with the softphone token as the bearer, for that rep’s own calls only. Those two routes answer requests from any website (the token is the credential, and no cookie is ever read), so they work from your own app’s pages. If Rydhm can’t be reached, hangup() still leaves the call in the browser, then rejects (and emits error) saying the other side may still be on: end it from your server with POST /v1/rep-calls/{id}/hangup.

To try it without writing a page, open demo/softphone.html from the @rydhm/web package, paste the token reply your server got, and choose Go online. The examples/sdr-node folder has the whole flow, server and page.

See the Browser SDK reference for every option and event.