> 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.

# Rep calls

Rep calls are for teams where a **person** makes the call. Your app (a dialer, a CRM, an SDR tool) stays in charge: it decides who to call and shows the rep's screen. Rydhm does the phone line and listens:

* **Live transcript** of both sides, labelled rep and prospect.
* **Suggestions**: after each thing the prospect says, the next question the rep could ask, from the call's context.
* **Detection**: whether a person, a voicemail or a call-screening assistant answered, and the voicemail beep.
* **AI voicemail on demand**: one click and the AI waits for the beep, leaves a message written for this prospect, and hangs up, while the rep moves on to the next call. See [AI voicemail](/engine/ai-voicemail).
* **Callbacks**: when a prospect calls back, it rings the right rep in the browser, then on their mobile, then voicemail. See [Callbacks and number pools](/engine/callbacks-and-pools).
* **A summary** after the call: what was agreed, the outcome, a callback time when they asked for one.
* **Recordings**, when you ask for one and your workspace's policy allows it: an MP3 of the call, the rep on one side and the prospect on the other. See [Recordings](#recordings).

> **Tip**
>
> New here? [Sales calls in three steps](/engine/sales-calls-quickstart) is the short version: a key, one server route file, the phone on your page. Building an app other teams connect to? See [Connect Rydhm](/developers/connect-with-rydhm).

> **Note**
>
> Rep calls are in **preview**: the routes on this page are live for early-access workspaces (`https://api-staging.rydhm.ai`), and small changes are still possible before launch. In the app, everything lives under **Sales calls** (Calls, Team, Numbers and Settings), and the guide for your own app under **Developers → Sales calls**.

## How it fits together

```mermaid
flowchart LR
    subgraph app [Your SDR app]
        S["Your server<br />(secret API key)"]
        B["Rep's browser<br />(@rydhm/web Softphone)"]
    end
    S -- "REST: reps, calls, voicemail, hang up" --> API["Rydhm API"]
    API -- "live events (SSE) and webhooks" --> S
    S -- "softphone token, call join token" --> B
    B <-- "audio (WebRTC) and live events" --> R["Rydhm call room"]
    API --- R
    L["Rydhm listener:<br />transcripts, suggestions,<br />detection, AI voicemail"] --- R
    R <-- "phone network" --> P["Prospect's phone"]
```

* **Your server** holds the secret key. It mints softphone tokens (which add the rep the first time), starts calls, follows their events and acts on them.
* **The rep's browser** runs the [softphone](/engine/softphone): it's online while it's connected, joins each call with the token your server hands it, and rings for callbacks.
* **Rydhm** connects the call to the phone network and listens to both sides. The AI says nothing to the prospect unless you ask for an AI voicemail, or your workspace records calls with a spoken notice (see [Recordings](#recordings)).

One outbound call, end to end:

```mermaid
sequenceDiagram
    participant Srv as Your server
    participant API as Rydhm API
    participant SP as Rep's softphone
    participant P as Prospect
    Srv->>API: POST /v1/reps/usr_4821/softphone-token { name } (adds the rep the first time)
    Srv-->>SP: { url, token } (the rep is online)
    Srv->>API: POST /v1/rep-calls { rep, to, context }
    API-->>Srv: { id, status, join }
    Srv-->>SP: join (the rep joins the call)
    API->>P: rings
    Srv->>API: GET /v1/rep-calls/{id}/events (stream)
    API-->>Srv: call.ringing, call.answered, call.transcript, call.suggestion…
    Srv->>API: POST /v1/rep-calls/{id}/voicemail (a machine answered)
    API-->>Srv: call.voicemail_left, call.ended, call.summary
```

## Server quickstart

#### Create a key

In **Developers → Sales calls**, click **Create a key for sales calls** (`calls:read` and `calls:write`). Store it on your server as `RYDHM_API_KEY`. A key limited to some experts can place calls but can't manage number pools.

#### Put the person online

Mint a softphone token with who is signed in (`{ name }`) and hand the whole reply to their browser. The first time, Rydhm adds them as a rep, keyed by **your** user id: there is no separate step. See [Softphone](/engine/softphone).

#### Start a call

Give it the rep, the number, and what the call is about. Hand `join` to the rep's browser.

#### Follow it, and act

Read the call's events, leave an AI voicemail when a machine answers, hang up when you're done.

#### TypeScript

**`server.ts`**

```typescript title="server.ts"
import { Rydhm } from "@rydhm/sdk";

const rydhm = new Rydhm(); // RYDHM_API_KEY (calls:write)

// 1. Their softphone token: send the whole object to their browser. The first time, Rydhm adds them
//    as a rep (by your user id).
const token = await rydhm.reps.softphoneToken("usr_4821", { name: "Maya Patel", mobileNumber: "+14155550101" });
// { url, token, presenceRoom, expiresAt }

// 2. Start a call. No `from`: one of your numbers for sales calls. The idempotency key (your activity id)
//    means a retry never dials twice.
const call = await rydhm.repCalls.create(
  {
    rep: "usr_4821",
    to: "+14155550199",
    externalRef: "act_77120",
    suggestions: true,
    waitForRep: true, // dial once the rep's softphone has joined
    context: {
      prospect: { name: "Dana Kim", title: "VP Sales", company: "Acme" },
      goal: "Book a 30-minute demo",
      notes: "Downloaded the pricing guide yesterday.",
    },
  },
  { idempotencyKey: "act_77120" },
);
// Send call.join to the rep's browser: softphone.join(call)

// 3. Follow it. The stream reconnects by itself and ends after call.completed, the last event of every call.
for await (const e of rydhm.repCalls.events(call.id)) {
  switch (e.type) {
    case "call.answered":
      if (e.data.by === "machine") await rydhm.repCalls.leaveVoicemail(call.id); // AI voicemail, rep released
      break;
    case "call.transcript":
      if (e.data.final) console.log(`${e.data.speaker}: ${e.data.text}`);
      break;
    case "call.suggestion":
      console.log("Try:", e.data.text);
      break;
    case "call.summary":
      console.log(e.data.outcome, e.data.summary, e.data.callbackAt);
      break;
  }
}

// 4. Or end it yourself.
await rydhm.repCalls.hangup(call.id);
```

#### Python

**`server.py`**

```python title="server.py"
from rydhm import Rydhm

client = Rydhm()  # RYDHM_API_KEY (calls:write)

# Adds the rep the first time (by your user id): no separate step.
token = client.reps.softphone_token("usr_4821", name="Maya Patel", mobile_number="+14155550101")  # .url, .token, …

call = client.rep_calls.create(
    rep="usr_4821",
    to="+14155550199",
    external_ref="act_77120",
    suggestions=True,
    wait_for_rep=True,  # dial once the rep's softphone has joined
    context={
        "prospect": {"name": "Dana Kim", "title": "VP Sales", "company": "Acme"},
        "goal": "Book a 30-minute demo",
    },
    idempotency_key="act_77120",
)
# Send call.join (url, token) to the rep's browser.

for event in client.rep_calls.events(call.id):
    if event.type == "call.answered" and event.data.by == "machine":
        client.rep_calls.leave_voicemail(call.id)
    elif event.type == "call.transcript" and event.data.final:
        print(f"{event.data.speaker}: {event.data.text}")
    elif event.type == "call.summary":
        print(event.data.outcome, event.data.summary)

client.rep_calls.hangup(call.id)
```

#### HTTP

```bash
# Start a call
curl https://api.rydhm.ai/v1/rep-calls \
  -H "Authorization: Bearer $RYDHM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: act_77120" \
  -d '{"rep":"usr_4821","to":"+14155550199","externalRef":"act_77120","suggestions":true}'
# → {"id":"4b5c6d7e-…","status":"ringing","join":{"url":"wss://…","token":"…"}}

# Follow it (Server-Sent Events; send Last-Event-ID to resume after a drop)
curl -N https://api.rydhm.ai/v1/rep-calls/4b5c6d7e-…/events \
  -H "Authorization: Bearer $RYDHM_API_KEY" -H "Accept: text/event-stream"
```

The `examples/sdr-node` folder is this flow as a small Express server and one page (a softphone, a dial box, the live transcript, **Leave AI voicemail** and **Hang up** buttons, and incoming callbacks); `examples/python-quickstart` is the same flow in Python. Copy them as a starting point.

## Starting a call

`POST /v1/rep-calls` (`rydhm.repCalls.create`):

| Field                   | Required | What it is                                                                                                                                                                                                                                                                                                          |
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rep`                   | Yes      | The rep's id in your app (their `externalId`), or `{ id, name, mobileNumber? }` to add the rep with the call (or update a changed name or mobile).                                                                                                                                                                  |
| `to`                    | Yes      | Who to call: `+14155550199`, or a US number in any common format.                                                                                                                                                                                                                                                   |
| `from`                  | No       | One of your numbers to call from (its id or E.164), or `pool:<id>` for a group. By default, one of your numbers for sales calls (**Sales calls → Numbers**, "Use for sales calls"), taking turns and under each number's daily limit. See [Callbacks and number pools](/engine/callbacks-and-pools).                |
| `context`               | No       | Who the prospect is and what the call is for, up to 16 KB of JSON. See [The context packet](#the-context-packet).                                                                                                                                                                                                   |
| `externalRef`           | No       | Your id for this call (an activity id). It comes back on the call, on its live events and on every webhook.                                                                                                                                                                                                         |
| `suggestions`           | No       | Suggest the next question after each prospect turn. Default `false`. Leave it off when your app writes its own suggestions from the live transcript.                                                                                                                                                                |
| `record`                | No       | Record the call. Whether it is recorded follows your workspace's recording policy and the prospect's number; the answer's `recording` says what was decided. Default `false`. See [Recordings](#recordings).                                                                                                        |
| `callingHoursException` | No       | `{ reason, note? }`: call outside 8 am to 9 pm the prospect's time, for a reason the rule doesn't cover. See [Calling hours](#calling-hours).                                                                                                                                                                       |
| `waitForRep`            | No       | Dial the prospect only once the rep's softphone has joined the call, so nobody answers to silence. Recommended for browser softphones. If the rep hasn't joined within 20 seconds, the call ends `canceled` with `endReason: "rep_not_joined"` and the prospect's phone never rings. Default `false`: dial at once. |

The answer is `{ id, status, join: { url, token }, endReason, recording }`. `join` is a short-lived token for the call's room: hand it to the rep's browser straight away (`softphone.join(call)`). Always send an `Idempotency-Key`, so a retried request can't dial the prospect twice. When the carrier refuses the call at once, `status` is `failed` and `endReason` says why (`invalid_number`, `carrier_rejected`, `dial_failed`…); while it rings, `endReason` is `null`. `recording` says whether the call will be recorded: `pending`, `skipped` with a `reason`, or `not_requested`.

### The context packet

`context` is what Rydhm knows about the call: the suggestions and the [AI voicemail](/engine/ai-voicemail) are written from it. These keys are read by name; anything else you add is read as part of the notes.

The summary records only what was said on the call. From the packet it reads just who the call is with and what it is for (`prospect` name, title and company, `company.name`, `goal`, `seller.company`), never `notes`, `playbook` or other keys, so earlier calls and internal notes don't end up in it.

| Key                     | What it is                                                                                                                                                                                                             |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prospect`              | `name`, `title`, `company`, and anything else about the person (`timezone`, `linkedin`…).                                                                                                                              |
| `company`               | The prospect's company: `name`, size, industry, the tools they use.                                                                                                                                                    |
| `goal`                  | What this call is for, in a few words ("Book a 30-minute demo").                                                                                                                                                       |
| `notes`                 | What your rep should know: earlier touches, what they downloaded, what they said last time.                                                                                                                            |
| `playbook`              | Your sales playbook for this call, as text: the products that fit, the questions to ask, objections and their answers. The suggestions and the AI voicemail ground themselves in it (about 6,000 characters are read). |
| `seller`                | Who is calling: `seller.company` is the company your rep calls for, said in the AI voicemail ("…on behalf of Maya at Acme") and used by the suggestions and the summary. Default: your Rydhm workspace's name.         |
| `language`, `languages` | The language of the call (BCP-47, `en`, `es-US`), or up to five it may switch between. Default English.                                                                                                                |

```json
{
  "prospect": { "name": "Dana Kim", "title": "VP Sales", "company": "Northwind", "timezone": "America/Los_Angeles" },
  "company": { "name": "Northwind", "size": "50 people", "crm": "HubSpot" },
  "goal": "Book a 30-minute demo",
  "notes": "Downloaded the AI receptionist guide last week. Two earlier calls: no answer.",
  "playbook": "AI Receptionist: answers inbound calls 24/7, books meetings. Ask: how many inbound calls a week; who answers after hours; which CRM.",
  "seller": { "company": "Acme" },
  "language": "en"
}
```

Rydhm treats the packet as data, never as instructions: text inside it can't change what the AI does.

The same rules as every Rydhm phone call apply: US numbers only, your **Do not call** list, and calling hours. See [US-only dialling](/channels/phone#us-only-dialling). When a call can't be placed, the error says why:

| Status | `error`                               | Why                                                                                                                                                                                                                            |
| ------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | `not_dialable`                        | Not a number that can be called: not a US number, a Rydhm number that rings reps (callbacks), or the number the call would go out from. A Rydhm number an **expert** answers can be called, so you can try your own AI expert. |
| `400`  | `do_not_call`                         | The number is on your workspace's do-not-call list.                                                                                                                                                                            |
| `400`  | `outside_calling_hours`               | It's outside 8 am to 9 pm where the person is (stricter in some states). The error says when it opens and what time it is there. See [Calling hours](#calling-hours).                                                          |
| `400`  | `invalid_hours_exception`             | `callingHoursException` has a `reason` that isn't one of the three, or a `note` over 200 characters.                                                                                                                           |
| `400`  | `no_number`, `number_not_ready`       | No pool number to call from, or the number isn't set up to call out yet.                                                                                                                                                       |
| `400`  | `context_too_large`                   | `context` is over 16 KB of JSON.                                                                                                                                                                                               |
| `402`  | `payment_required`                    | Out of credits.                                                                                                                                                                                                                |
| `403`  | `hours_exception_not_allowed`         | You sent `callingHoursException`, and your workspace has calling-hours exceptions turned off.                                                                                                                                  |
| `404`  |                                       | No such rep (`PUT /v1/reps/{externalId}` first), or no such pool.                                                                                                                                                              |
| `429`  | `pool_exhausted`, `concurrency_limit` | Every number in the pool made its calls for today, or too many calls are live. The SDKs don't retry these: a retry wouldn't succeed.                                                                                           |
| `429`  | `rate_limited`                        | Too many requests: wait `Retry-After` seconds (the SDKs do).                                                                                                                                                                   |
| `503`  |                                       | Phone calls are switched off on the server, or outbound calling is paused.                                                                                                                                                     |

### Calling hours

Rydhm places a rep call only between 8 am and 9 pm where the prospect is, by their area code. Some states are stricter, and Rydhm holds calls to their hours too. Outside them, `POST /v1/rep-calls` answers `400 outside_calling_hours` with what your app needs to tell the rep why, and when to try again:

```json
{
  "statusCode": 400,
  "error": "outside_calling_hours",
  "message": "It’s outside calling hours where this person is (8 am–9 pm their time, stricter in some states).",
  "retryAt": "2026-11-18T16:00:00.000Z",
  "timeZone": "America/Los_Angeles",
  "localTime": "22:45",
  "state": "CA",
  "exceptionsAllowed": true
}
```

| Field               | What it is                                                                                             |
| ------------------- | ------------------------------------------------------------------------------------------------------ |
| `retryAt`           | When the person may next be called. `null` when that isn't within a week.                              |
| `timeZone`          | Their time zone (IANA). `null` when their area code spans more than one zone, or Rydhm can't place it. |
| `localTime`         | The time where they are now, `HH:MM` (24-hour). `null` when `timeZone` is.                             |
| `state`             | Their US state, by area code. `null` when unknown.                                                     |
| `exceptionsAllowed` | Whether your workspace accepts `callingHoursException`.                                                |

**Calling outside the hours.** The federal hours rule (47 CFR 64.1200(c)(1)) covers telephone solicitations to residential subscribers. Some calls are outside it. When the rep has one of these reasons, send `callingHoursException` with the call:

| `reason`            | When                                                       |
| ------------------- | ---------------------------------------------------------- |
| `prospect_asked`    | The person asked for a call at this time, or agreed to it. |
| `existing_customer` | The person is an existing customer.                        |
| `business_line`     | The number is a business line, not a home.                 |

`note` is optional: a few words for the record ("Asked for a call after 9"), up to 200 characters.

* It skips the calling-hours check and nothing else. Your do-not-call list, credits and every other rule still apply.
* It counts only when the call is actually outside the hours. Then it's kept on the call (`callingHoursException: { reason, note }` on `GET /v1/rep-calls/{id}`) and in the audit log, and the `call.completed` webhook carries `calling_hours_exception: { reason }` (never the note). Inside the hours it's ignored, and `callingHoursException` is `null`.
* Exceptions are on by default. A workspace admin can turn them off in **Sales calls** → **Settings** → **Calling hours** → **Allow exceptions with a reason** (`repCallHoursExceptions` in the workspace policies). Then any call that sends one gets `403 hours_exception_not_allowed`, and `outside_calling_hours` says `exceptionsAllowed: false`.

#### TypeScript

```typescript
import { BadRequestError } from "@rydhm/sdk";

const params = { rep: "usr_4821", to: "+19495550142", externalRef: "act_77121" };
try {
  await rydhm.repCalls.create(params, { idempotencyKey: "act_77121" });
} catch (err) {
  if (!(err instanceof BadRequestError) || err.code !== "outside_calling_hours") throw err;
  const hours = err.body as { localTime: string | null; retryAt: string | null; exceptionsAllowed: boolean };
  // Show the rep: "It's 22:45 there. Next window: …". If the prospect asked for this call:
  if (hours.exceptionsAllowed && prospectAskedForThisCall) {
    await rydhm.repCalls.create(
      { ...params, callingHoursException: { reason: "prospect_asked", note: "Asked for a call after 9" } },
      { idempotencyKey: "act_77121" },
    );
  }
}
```

#### Python

```python
from rydhm import BadRequestError

try:
    client.rep_calls.create(rep="usr_4821", to="+19495550142", external_ref="act_77121", idempotency_key="act_77121")
except BadRequestError as e:
    if e.code != "outside_calling_hours":
        raise
    print("It's", e.body["localTime"], "there. Next window:", e.body["retryAt"])
    if e.body["exceptionsAllowed"] and prospect_asked_for_this_call:
        client.rep_calls.create(
            rep="usr_4821",
            to="+19495550142",
            external_ref="act_77121",
            calling_hours_exception={"reason": "prospect_asked", "note": "Asked for a call after 9"},
            idempotency_key="act_77121",
        )
```

#### HTTP

```bash
curl https://api.rydhm.ai/v1/rep-calls \
  -H "Authorization: Bearer $RYDHM_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: act_77121" \
  -d '{"rep":"usr_4821","to":"+19495550142","externalRef":"act_77121",
       "callingHoursException":{"reason":"prospect_asked","note":"Asked for a call after 9"}}'
```

A refused request frees its `Idempotency-Key`, so the second try can use the same one.

This isn't legal advice. Check which calls the rules cover with your own counsel.

## Follow the call

Two streams of [the same events](/engine/overview#one-event-shape-everywhere), as Server-Sent Events, with `calls:read`:

| Stream                                                            | What it carries                                                                    |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `GET /v1/rep-calls/{id}/events` (`rydhm.repCalls.events(id)`)     | One call, from ringing to its summary.                                             |
| `GET /v1/events/stream?repId=` (`rydhm.events.stream({ repId })`) | Every call of one rep, and `call.incoming` when a callback rings them. Stays open. |

Each event is one `data:` line of JSON with its `id:` line, and a `: ping` comment comes every 15 seconds. Each event carries the call's `callId` and, when you started it with one, its `externalRef`. A **call's** stream starts with everything the call has had so far (up to 500 events, kept for an hour), so opening it late still shows the whole call; the **rep's** stream starts from now. Reconnect with the last `id` you saw as `Last-Event-ID` (or `?lastEventId=` for clients that can't send headers) to get only what you missed.

A call's stream **ends after `call.completed`**, the last event of every call (answered or not), so no client waits on heartbeats once the call is over. The SDKs' streams do all of that for you: they reconnect after a dropped connection, resume with `Last-Event-ID`, skip heartbeats, and drop repeats by `id`. `rydhm.repCalls.events` ends after `call.completed` (or pass `until: "summary"` or `until: "ended"`); pass `types: ["call.transcript", "call.suggestion"]` to get only some.

| Event                     | `data`                                                                            | When                                                                                                                                                                                                                                                                                                                                                  |
| ------------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `call.ringing`            | `from`, `to`                                                                      | The prospect's phone is ringing.                                                                                                                                                                                                                                                                                                                      |
| `call.answered`           | `by`: `human`, `machine` or `screening`                                           | Something picked up.                                                                                                                                                                                                                                                                                                                                  |
| `call.screening`          | `text?`                                                                           | A call-screening assistant answered (Google Call Screen, iOS screening).                                                                                                                                                                                                                                                                              |
| `call.voicemail_detected` | `greeting?`                                                                       | A voicemail greeting is playing.                                                                                                                                                                                                                                                                                                                      |
| `call.beep`               | `atMs`                                                                            | The voicemail beep: the prospect's voicemail is taking a message.                                                                                                                                                                                                                                                                                     |
| `call.transcript`         | `speaker` (`rep`, `prospect` or `ai`), `text`, `final`, `startMs`                 | A transcript line. The streams carry finished lines (`final: true`); the softphone in the call room also gets the interim ones, each replaced by the next line with the same speaker and `startMs`.                                                                                                                                                   |
| `call.suggestion`         | `text`                                                                            | The next thing the rep could ask.                                                                                                                                                                                                                                                                                                                     |
| `call.voicemail_left`     | `text`, `voice`, `by?`, `from?`                                                   | A voicemail was left, with its words. `by`: `ai` (the default), `rep` (the rep spoke their own message after the beep), or `caller` (on a callback that reached the voicemail step, with their number in `from`).                                                                                                                                     |
| `call.voicemail_failed`   | `reason`                                                                          | An AI voicemail you asked for didn't happen: `not_answered`, `not_outbound`, `line_gone` or `no_audio`. The rep can leave their own.                                                                                                                                                                                                                  |
| `call.recording`          | `status`, `reason`, `notice`                                                      | The call's [recording](#recordings). `recording`: it started at the answer (show a REC badge; `notice: true` when Rydhm's voice says the notice). `skipped`: it isn't recorded, with the `reason`. `ready`: the file is stored, usually after `call.completed`, so it reaches the rep's stream rather than the call's. `failed`: it couldn't be kept. |
| `call.ended`              | `outcome`, `durationSec`                                                          | The call ended: `conversation`, `voicemail_left`, `machine`, `screened`, `no_answer`, `busy`, `failed` or `canceled`.                                                                                                                                                                                                                                 |
| `call.summary`            | `summary`, `outcome`, `callbackAt?`, `facts`, `wrongNumber?`                      | A few seconds after the call: what happened, `meeting_booked`, `callback`, `interested`, `not_interested`, `wrong_contact`, `no_conversation` or `other`, what was learned by label (`"Seats": "40"`), and whether it reached the wrong person.                                                                                                       |
| `call.completed`          | `outcome`, `durationSec`, `voicemailBy`, `summary`, `transcriptLines`             | The call's record is final: the last event of every call, after `call.summary` when there is one (`summary: true`). The stream ends after it; read the record with `GET /v1/rep-calls/{id}`. Also a [webhook](#webhooks).                                                                                                                             |
| `call.incoming`           | `callId`, `from`, `repId`, `repExternalId`, `externalRef?`, `join`, `ringSeconds` | A callback is ringing the rep. See [Callbacks](/engine/callbacks-and-pools).                                                                                                                                                                                                                                                                          |

The rep's browser gets the same events in the call room (the transcript there includes the interim lines), so the softphone can show the live transcript and suggestions without your server relaying them.

### Use your own coach

If your app already has a coach (your playbooks, your CRM's history of the account, your own model), keep it. Rydhm gives it the words; your app shows the card.

1. Leave `suggestions` off when you start the call. It's off by default.
2. Read the call's `call.transcript` events and keep the finished lines from the prospect (`final: true`, `speaker: "prospect"`).
3. Give each one to your coach, and show its answer on the rep's screen, where your app shows its cards.

#### TypeScript

```typescript
const call = await rydhm.repCalls.create(
  { rep: "usr_4821", to: "+14155550199", externalRef: "act_77120", context }, // suggestions: off (the default)
  { idempotencyKey: "act_77120" },
);

for await (const e of rydhm.repCalls.events(call.id, { types: ["call.transcript"] })) {
  if (e.data.final && e.data.speaker === "prospect") {
    const card = await yourCoach.next(e.data.text); // your playbooks, your history
    showOnRepScreen("usr_4821", card);
  }
}
```

#### Python

```python
call = client.rep_calls.create(
    rep="usr_4821", to="+14155550199", external_ref="act_77120", context=context,  # suggestions: off (the default)
    idempotency_key="act_77120",
)

for event in client.rep_calls.events(call.id, types=["call.transcript"]):
    if event.data.final and event.data.speaker == "prospect":
        card = your_coach.next(event.data.text)  # your playbooks, your history
        show_on_rep_screen("usr_4821", card)
```

Each finished line arrives on the call's stream about half a second after the softphone shows it, and about a second after the person stops speaking. Interim lines reach only the softphone, for display. Use one coach per call: with both on, the rep gets two cards that can disagree.

Rydhm's own suggestions are there for apps without a coach. Pass `suggestions: true`, and they ground themselves in the call's [`context.playbook`](#the-context-packet) and the rest of the context.

## After the call

Every call ends with one record, whatever happened: answered, voicemail, screened, no answer.

| Call                                               | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /v1/rep-calls/{id}` (`get`)                   | The call: `status`, how it ended (`outcome`), numbers, who answered (`answeredBy`), the voicemail (`voicemail`: its `text`, `by` (`ai`, `rep` or `caller`), when the AI was asked to leave it (`requestedAt`) and the [consent](/engine/ai-voicemail#record-the-consent) sent with that request; `voicemailText` and `voicemailBy` still work), the callback time, the routing step of a callback (`routeStep`), timings, `summary` once it's ready, the whole `transcript`, the [`recording`](#recordings)'s state, and the `callingHoursException` the call went out under (or `null`). |
| `GET /v1/rep-calls/{id}/transcript` (`transcript`) | Every finished line, both sides and the AI's, in the order they were said, a page at a time (`limit` up to 5,000, default 1,000; `cursor`). During a call: what has been said so far. Each line is `{ id, speaker, text, final, startMs, at }`; `id` is its `call.transcript` event's id, so you can match the lines you already read live.                                                                                                                                                                                                                                               |

`outcome` is how the call ended: `conversation`, `voicemail_left` (whenever a voicemail is on the call; `voicemailBy` says whose), `machine` (a voicemail answered and no message was left), `screened` (a call-screening assistant answered), `no_answer`, `busy`, `failed` or `canceled`. A wrong number is the summary's `wrongNumber`.

#### TypeScript

```typescript
const call = await rydhm.repCalls.get(callId);
console.log(call.outcome, call.durationSec, call.voicemailText, call.summary?.summary);
for (const line of call.transcript ?? []) console.log(`${line.speaker}: ${line.text}`);

// Or the transcript alone, page after page:
for await (const line of rydhm.repCalls.transcript(callId)) console.log(line.startMs, line.speaker, line.text);
```

#### Python

```python
call = client.rep_calls.get(call_id)
print(call.outcome, call.duration_sec, call.voicemail_text, call.summary and call.summary.summary)

for line in client.rep_calls.transcript(call_id):
    print(line.start_ms, line.speaker, line.text)
```

#### HTTP

```bash
curl https://api.rydhm.ai/v1/rep-calls/$CALL_ID/transcript -H "Authorization: Bearer $RYDHM_API_KEY"
# → {"items":[{"id":"evt_…","speaker":"prospect","text":"Hello, this is Dana.","final":true,"startMs":2600,"at":"…"}],"nextCursor":null}
```

The [`call.completed` webhook](#webhooks) tells you when the record is final.

## Act on a call

| Call                                                           | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /v1/rep-calls/{id}/voicemail` (`leaveVoicemail`)         | The AI waits for the beep, speaks, and hangs up. `releaseRep: false` keeps the rep listening, with their microphone off the call. `consent` records where the prospect's consent to an AI voice came from. `403 ai_voicemail_off` while AI voicemail is off for the workspace; `409 not_answered` while it still rings, `409 call_over` once the call ended, `409 not_outbound` on a callback, `409 ai_not_in_call` in the first moments before the listener joined; `400 invalid_voice` for a voice Rydhm can't speak, `400 invalid_consent` for a `consent` that isn't valid. See [AI voicemail](/engine/ai-voicemail). |
| `GET /v1/rep-calls/{id}/recording` (`recording`)               | The call's recording, with a link to the MP3 that works for 10 minutes while it's `ready`. See [Recordings](#recordings).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `DELETE /v1/rep-calls/{id}/recording` (`deleteRecording`)      | Deletes the recording. The call, its transcript and its summary stay. Safe to repeat.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `POST /v1/rep-calls/{id}/hangup` (`hangup`)                    | Ends the call for everyone. Safe to repeat.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `POST /v1/rep-calls/{id}/decline` (`decline`)                  | Turns down a ringing callback: its routing moves on at once. `409 not_ringing` when it isn't ringing the rep's browser.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `GET /v1/rep-calls?repId=&status=&externalRef=` (`list`)       | Calls, newest first, 50 a page (`limit` up to 100), paged with `cursor`. `repId` is the rep's id in your app. Lists leave out the transcript.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `GET /v1/reps`, `GET` / `PUT` / `DELETE /v1/reps/{externalId}` | List reps (with `online`), read, create or update, and remove one (their past calls stay).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `GET /v1/voices` (`voices.list`)                               | The voices for Rydhm's own lines, each with a free sample, and the workspace's default. See [Rydhm's voice on a call](#rydhms-voice-on-a-call).                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

## Rydhm's voice on a call

Your reps talk in their own voices. Rydhm's voice says only its own lines: the [AI voicemail](/engine/ai-voicemail), the [recording notice](#which-calls-are-recorded), and the message prompt on a callback nobody picks up. One call, one voice, chosen in this order:

1. The `voice` sent with `POST /v1/rep-calls/{id}/voicemail` (that voicemail only).
2. The rep's `voicemailVoice` (`PUT /v1/reps/{externalId}`).
3. The workspace's voice, set by an admin in **Sales calls** → **Settings** → **Voicemail voice**.
4. Rydhm's default, Blake.

A rep whose `voicemailVoice` is `null` follows the workspace's voice. `GET /v1/voices` lists the voices to pick from, each with a free sample. See [Choose the voice](/engine/ai-voicemail#choose-the-voice).

The rep's softphone token can also hang up and decline that rep's own calls, straight from the rep's browser on your own site (those two routes answer any origin; the token is the credential), so the browser doesn't need your server for those.

## Recordings

Pass `record: true` when you start a call. Whether Rydhm records it is decided right then, from your workspace's recording policy and the prospect's number, and the answer's `recording` says what was decided.

### Which calls are recorded

Some US states require everyone on a call to agree to its recording. Rydhm decides by the prospect's area code (where the number was issued, which isn't always where the person is). A workspace admin picks one of three modes in **Sales calls** → **Settings** → **Recordings** → **Which calls are recorded** (`repCallRecordings` in the workspace policies):

| Mode                             | What `record: true` does                                                                                                                                                                                                                                        |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `one_party_states` (the default) | Records the call only when the prospect's number is in a US state where one person's agreement is enough. Any other number: `skipped`, `reason: "all_party_state"`.                                                                                             |
| `all_with_notice`                | Records every call you ask for. Where everyone must agree, Rydhm's voice says "Just so you know, this call is recorded." right after a person answers, and `recording.notice` is `true`. The notice is in the recording, and in the transcript as an `ai` line. |
| `off`                            | Never records. A call that asks: `skipped`, `reason: "workspace_off"`.                                                                                                                                                                                          |

* **States where everyone must agree**, as Rydhm counts them: CA, CT, DE, FL, IL, MD, MA, MI, MT, NV, NH, PA and WA. The list is cautious: a state whose courts have read its law either way is on it.
* **Numbers Rydhm can't place count as all-party**: an unknown area code, a Canadian or Caribbean `+1` number, a US territory, and any number outside `+1`.
* **A callback** is decided by the caller's number.
* **The notice** is said to a person or their call-screening assistant, never to a voicemail machine. If it can't be said, the call isn't recorded (`failed`).

Your rep is on the call too: tell them which mode your workspace uses. Rydhm's choice by area code is a cautious default, not legal advice. Check the rules that apply to your calls with your own counsel.

### The recording object

`recording` is on the answer to `POST /v1/rep-calls`, on `GET /v1/rep-calls/{id}` and on each call in a list:

```json
"recording": {
  "requested": true,
  "status": "ready",
  "reason": null,
  "notice": false,
  "durationSeconds": 184,
  "bytes": 1104000,
  "format": "audio/mpeg",
  "readyAt": "2026-11-11T15:09:30.000Z"
}
```

| `status`        | What it means                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `not_requested` | The call didn't ask (`record` was `false`).                                                                                         |
| `pending`       | It will be recorded from the answer.                                                                                                |
| `recording`     | It's being recorded now.                                                                                                            |
| `processing`    | The call is over and the file is being uploaded.                                                                                    |
| `ready`         | The file is stored: [get it](#get-the-file).                                                                                        |
| `skipped`       | It isn't recorded. `reason`: `workspace_off`, `all_party_state`, or `not_answered` (nobody picked up).                              |
| `failed`        | It couldn't be kept. `reason`: `upload_failed`, or `worker_lost` (the listener never delivered it, or the notice couldn't be said). |
| `deleted`       | You deleted it, or your workspace's retention did.                                                                                  |

* **What's in it**: one MP3 (`audio/mpeg`), stereo. The left channel is the rep, and Rydhm's own voice (the notice, an AI voicemail); the right channel is the prospect.
* **When it runs**: from the answer (a person, a voicemail or a call-screening assistant; on a callback, the rep's pick-up) to the end of the call. Never while it rings.
* **How long**: the first 4 hours of a call. A longer call is `ready` with `reason: "too_long"`.
* `durationSeconds`, `bytes` and `readyAt` are set once it's `ready`. `notice` says whether the notice is (or was) said on this call.

### Get the file

`GET /v1/rep-calls/{id}/recording` (`calls:read`) answers with the recording object, plus `url` and `expiresAt`. While `status` is `ready`, `url` is a signed link to the MP3 that works for 10 minutes; otherwise both are `null`. Ask again for a fresh link. It answers `200` for any call that exists, recorded or not.

`DELETE /v1/rep-calls/{id}/recording` (`calls:write`) deletes the file, and the recording reads `deleted`. The call, its transcript and its summary stay. It's safe to repeat, and each delete is in the [audit log](/workspace/security#audit-log). `503 storage_unavailable` means the file store couldn't be reached: nothing changed, try again.

#### TypeScript

```typescript
const rec = await rydhm.repCalls.recording(callId);
if (rec.status === "ready") {
  const mp3 = await fetch(rec.url!); // the link works for 10 minutes: download it now
  await saveRecording(callId, new Uint8Array(await mp3.arrayBuffer()));
}

await rydhm.repCalls.deleteRecording(callId); // safe to repeat
```

#### Python

```python
import httpx

rec = client.rep_calls.recording(call_id)
if rec.status == "ready":
    mp3 = httpx.get(rec.url).content  # the link works for 10 minutes: download it now
    save_recording(call_id, mp3)

client.rep_calls.delete_recording(call_id)  # safe to repeat
```

#### HTTP

```bash
curl https://api.rydhm.ai/v1/rep-calls/$CALL_ID/recording -H "Authorization: Bearer $RYDHM_API_KEY"
# → {"requested":true,"status":"ready",…,"url":"https://…","expiresAt":"2026-11-11T15:19:30.000Z"}

curl -X DELETE https://api.rydhm.ai/v1/rep-calls/$CALL_ID/recording -H "Authorization: Bearer $RYDHM_API_KEY"
```

### Live, and after the call

* **During the call**: `call.recording` with `status: "recording"` comes when the recording starts at the answer. Show a REC badge. The rep's softphone gets it in the call room too (see [A REC badge](/developers/sdk-web#a-rec-badge)). A call the policy won't record sends `call.recording` with `status: "skipped"` and its `reason` on your server's streams as soon as it starts.
* **After the call**: the file is uploaded once the call ends, so the `call.completed` webhook usually says `recording.status: "processing"`. Wait for the `call.recording.ready` webhook, then get the link. Webhooks never carry a link to the file. `call.recording` with `status: "ready"` (or `failed`) comes at the same moment on the rep's stream, which stays open; the call's own stream has usually ended by then.

### How long recordings are kept

Recordings are kept until you delete them, unless an admin sets **Keep recordings** in **Sales calls** → **Settings** → **Recordings** (`retention.recordingsDays` in the workspace policies). Recordings older than that are deleted every night: the call, its transcript and its summary stay, and the recording reads `deleted`. When a call is deleted for good, its recording goes with it, and deleting the workspace deletes them all.

## Webhooks

`call.completed` is the one to build on: it's sent **once for every rep call**, answered or not, when its record is final (a few seconds after the end, after the summary when there is one). Like every Rydhm webhook it's thin: how the call ended, who answered, the timings, whose voicemail is on the call and how long it is, a snippet of the summary with its outcome and how many facts were noted, the recording's state, and links. The words (the full summary and its facts, the voicemail's text, the transcript, the recording) are one authenticated `GET` away, behind your key's scopes and your workspace's retention.

```json
{
  "type": "call.completed",
  "data": {
    "call": {
      "id": "4b5c6d7e-…", "mode": "rep", "direction": "outbound", "from": "+14155550123", "to": "+14155550199",
      "status": "completed", "outcome": "voicemail_left", "answered_by": "machine", "end_reason": "voicemail_left",
      "started_at": "…", "answered_at": "…", "ended_at": "…", "duration_seconds": 34,
      "callback_at": null, "route_step": null, "external_ref": "act_77120"
    },
    "rep": { "id": "8c9d…", "external_id": "usr_4821", "name": "Maya Patel" },
    "calling_hours_exception": null,
    "voicemail": { "by": "ai", "characters": 214 },
    "summary": {
      "snippet": "Reached Dana's voicemail; an AI voicemail was left…", "outcome": "no_conversation",
      "callback_at": null, "wrong_number": false, "facts": 0, "generated_at": "…"
    },
    "recording": { "status": "processing", "duration_seconds": null },
    "transcript": { "lines": 9 },
    "links": {
      "api": "https://api.rydhm.ai/v1/rep-calls/4b5c6d7e-…",
      "transcript": "https://api.rydhm.ai/v1/rep-calls/4b5c6d7e-…/transcript",
      "recording": "https://api.rydhm.ai/v1/rep-calls/4b5c6d7e-…/recording"
    }
  }
}
```

| Field                     | What it is                                                                                                                                                            |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `voicemail`               | `by` (`ai`, `rep` or `caller`) and `characters`, or `null`. The words are on the call: `voicemail.text`.                                                              |
| `summary`                 | `snippet` (up to 500 characters), `outcome`, `callback_at`, `wrong_number`, `facts` (how many were noted) and `generated_at`, or `null` when the call has no summary. |
| `recording`               | `status` (`ready`, `processing`, `skipped`, `failed`, `deleted` or `not_requested`) and `duration_seconds` (once `ready`).                                            |
| `calling_hours_exception` | `{ reason }` when the call went out under a [calling-hours exception](#calling-hours), else `null`.                                                                   |
| `transcript.lines`        | How many finished lines the transcript has.                                                                                                                           |
| `links`                   | `api` (the call), `transcript` and `recording`.                                                                                                                       |

`call.recording.ready` follows when the recording is stored: the call's ids, the rep, `recording: { duration_seconds, bytes, format }` and `links.recording`. `call.answered`, `call.voicemail_left`, `call.incoming` and `call.summary.ready` are [webhooks](/developers/webhooks#rep-calls-and-the-onboarding-coach) too, for the moments in between. All of them carry your `external_ref` and the rep's `external_id`, so your app can log the call even when nobody has the stream open.

### Fetch the record when a call completes

Verify the delivery, queue it and answer `204`. Then, in the job, fetch what you keep: the call's `GET` has the full summary and its facts, the voicemail's words and the transcript. The recording comes later, on `call.recording.ready`. Your key needs `calls:read`.

#### TypeScript

**`webhooks.ts`**

```typescript title="webhooks.ts"
import express from "express";
import { Rydhm, verifyWebhook, WebhookVerificationError, type WebhookEvent } from "@rydhm/sdk";

const rydhm = new Rydhm(); // RYDHM_API_KEY with calls:read
const app = express();

app.post("/webhooks/rydhm", express.raw({ type: "application/json" }), async (req, res) => {
  let event: WebhookEvent;
  try {
    event = verifyWebhook(process.env.RYDHM_WEBHOOK_SECRET!, req.headers, req.body); // the raw bytes
  } catch (err) {
    if (err instanceof WebhookVerificationError) return res.status(400).send(err.message);
    throw err;
  }
  await queue.add(event); // dedupe on event.id
  res.sendStatus(204);
});

// The job:
export async function handle(event: WebhookEvent) {
  if (event.type === "call.completed") {
    const call = await rydhm.repCalls.get(event.data.call.id);
    await crm.saveCall(event.data.call.external_ref, {
      outcome: call.outcome,
      summary: call.summary?.summary,
      facts: call.summary?.facts,
      voicemail: call.voicemail.text,
      transcript: call.transcript,
    });
  }
  if (event.type === "call.recording.ready") {
    const rec = await rydhm.repCalls.recording(event.data.call.id);
    if (rec.url) {
      const mp3 = await fetch(rec.url); // the link works for 10 minutes
      await crm.attachRecording(event.data.call.external_ref, new Uint8Array(await mp3.arrayBuffer()));
    }
  }
}
```

#### Python

**`webhooks.py`**

```python title="webhooks.py"
import os

import httpx
from flask import Flask, request
from rydhm import Rydhm, WebhookVerificationError, verify_webhook

client = Rydhm()  # RYDHM_API_KEY with calls:read
app = Flask(__name__)


@app.post("/webhooks/rydhm")
def rydhm_webhook():
    try:
        event = verify_webhook(os.environ["RYDHM_WEBHOOK_SECRET"], request.headers, request.get_data())
    except WebhookVerificationError as e:
        return str(e), 400
    queue.enqueue(handle, event)  # dedupe on event.id
    return "", 204


def handle(event):
    call_id = event.data["call"]["id"]
    ref = event.data["call"]["external_ref"]
    if event.type == "call.completed":
        call = client.rep_calls.get(call_id)
        crm.save_call(
            ref,
            outcome=call.outcome,
            summary=call.summary.summary if call.summary else None,
            facts=call.summary.facts if call.summary else {},
            voicemail=call.voicemail_text,
            transcript=call.transcript,
        )
    elif event.type == "call.recording.ready":
        rec = client.rep_calls.recording(call_id)
        if rec.url:
            crm.attach_recording(ref, httpx.get(rec.url).content)  # the link works for 10 minutes
```

## Disclosure

The transcript is the call's record, whether or not you record audio. Transcription means the call is recorded in the legal sense, and some US states require that everyone on the call is told. On a live call, your rep says it (or, under `all_with_notice`, Rydhm's voice says the [recording notice](#which-calls-are-recorded) where everyone must agree). For what the AI says itself, each workspace has a disclosure setting, on by default (**Sales calls** → **Settings** → **Recording, and telling people** → **The AI says it's an AI**): an AI voicemail says it's an automated message on the rep's behalf, and a caller leaving a message hears that it's recorded and transcribed. Admins change these settings in the app (`PATCH /v1/workspace/policies { "repCallDisclosure": … }` from a signed-in session; API keys can't). Check the rules that apply to your calls with your own counsel.

## What it costs

Provisional prices while rep calls are in preview: \$0.07 a minute of a rep call, and \$0.02 for each AI voicemail. Final prices will be on the [Billing](/workspace/billing) page before launch.