> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.rydhm.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.rydhm.ai/_mcp/server.

# Browser softphone

The softphone is the rep's side of a [rep call](/engine/rep-calls). 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.

```bash
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):

```html
<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](/developers/sdk-web#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.

#### Express

**`server.ts`**

```typescript title="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 }
});
```

#### Python

```python
from rydhm import Rydhm

client = Rydhm()

def softphone_token(rep):
    client.reps.upsert(rep.id, name=rep.name)
    return client.reps.softphone_token(rep.id).model_dump(by_alias=True)  # {"url", "token", "presenceRoom", "expiresAt"}
```

## 2. Go online in the browser

```typescript
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:

```typescript
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](/engine/ai-voicemail).

## 4. Take callbacks

When a prospect calls back one of your [pool numbers](/engine/callbacks-and-pools), it rings the rep's browser first:

```typescript
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

| Member                                                                                                          | What 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](/developers/sdk-web#softphone) for every option and event.