Skip to navigation

Rep calls

Your reps call prospects from the browser while Rydhm transcribes both sides, suggests the next question, leaves the voicemail and routes the callbacks.

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

New here? Sales calls in three steps 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.

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

Your SDR app phone network REST: reps, calls, voicemail, hang up live events (SSE) and webhooks audio (WebRTC) and live events softphone token, call join token Rydhm API Rydhm call room Rydhm listener:transcripts, suggestions,detection, AI voicemail Prospect's phone Your server(secret API key) Rep's browser(@rydhm/web Softphone)
  • 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: 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).

One outbound call, end to end:

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

Server quickstart

1

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.

2

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.

3

Start a call

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

4

Follow it, and act

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

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);

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

FieldRequiredWhat it is
repYesThe 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).
toYesWho to call: +14155550199, or a US number in any common format.
fromNoOne 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.
contextNoWho the prospect is and what the call is for, up to 16 KB of JSON. See The context packet.
externalRefNoYour id for this call (an activity id). It comes back on the call, on its live events and on every webhook.
suggestionsNoSuggest the next question after each prospect turn. Default false. Leave it off when your app writes its own suggestions from the live transcript.
recordNoRecord 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.
callingHoursExceptionNo{ reason, note? }: call outside 8 am to 9 pm the prospect’s time, for a reason the rule doesn’t cover. See Calling hours.
waitForRepNoDial 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 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.

KeyWhat it is
prospectname, title, company, and anything else about the person (timezone, linkedin…).
companyThe prospect’s company: name, size, industry, the tools they use.
goalWhat this call is for, in a few words (“Book a 30-minute demo”).
notesWhat your rep should know: earlier touches, what they downloaded, what they said last time.
playbookYour 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).
sellerWho 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, languagesThe language of the call (BCP-47, en, es-US), or up to five it may switch between. Default English.
{
"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. When a call can’t be placed, the error says why:

StatuserrorWhy
400not_dialableNot 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.
400do_not_callThe number is on your workspace’s do-not-call list.
400outside_calling_hoursIt’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.
400invalid_hours_exceptioncallingHoursException has a reason that isn’t one of the three, or a note over 200 characters.
400no_number, number_not_readyNo pool number to call from, or the number isn’t set up to call out yet.
400context_too_largecontext is over 16 KB of JSON.
402payment_requiredOut of credits.
403hours_exception_not_allowedYou sent callingHoursException, and your workspace has calling-hours exceptions turned off.
404No such rep (PUT /v1/reps/{externalId} first), or no such pool.
429pool_exhausted, concurrency_limitEvery 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.
429rate_limitedToo many requests: wait Retry-After seconds (the SDKs do).
503Phone 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:

{
"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
}
FieldWhat it is
retryAtWhen the person may next be called. null when that isn’t within a week.
timeZoneTheir time zone (IANA). null when their area code spans more than one zone, or Rydhm can’t place it.
localTimeThe time where they are now, HH:MM (24-hour). null when timeZone is.
stateTheir US state, by area code. null when unknown.
exceptionsAllowedWhether 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:

reasonWhen
prospect_askedThe person asked for a call at this time, or agreed to it.
existing_customerThe person is an existing customer.
business_lineThe 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.
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" },
);
}
}

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, as Server-Sent Events, with calls:read:

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

EventdataWhen
call.ringingfrom, toThe prospect’s phone is ringing.
call.answeredby: human, machine or screeningSomething picked up.
call.screeningtext?A call-screening assistant answered (Google Call Screen, iOS screening).
call.voicemail_detectedgreeting?A voicemail greeting is playing.
call.beepatMsThe voicemail beep: the prospect’s voicemail is taking a message.
call.transcriptspeaker (rep, prospect or ai), text, final, startMsA 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.suggestiontextThe next thing the rep could ask.
call.voicemail_lefttext, 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_failedreasonAn AI voicemail you asked for didn’t happen: not_answered, not_outbound, line_gone or no_audio. The rep can leave their own.
call.recordingstatus, reason, noticeThe call’s recording. 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.endedoutcome, durationSecThe call ended: conversation, voicemail_left, machine, screened, no_answer, busy, failed or canceled.
call.summarysummary, 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.completedoutcome, durationSec, voicemailBy, summary, transcriptLinesThe 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.
call.incomingcallId, from, repId, repExternalId, externalRef?, join, ringSecondsA callback is ringing the rep. See Callbacks.

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.
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);
}
}

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 and the rest of the context.

After the call

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

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

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);

The call.completed webhook tells you when the record is final.

Act on a call

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

Rydhm’s voice on a call

Your reps talk in their own voices. Rydhm’s voice says only its own lines: the AI voicemail, the recording notice, 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.

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

ModeWhat 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_noticeRecords 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.
offNever 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:

"recording": {
"requested": true,
"status": "ready",
"reason": null,
"notice": false,
"durationSeconds": 184,
"bytes": 1104000,
"format": "audio/mpeg",
"readyAt": "2026-11-11T15:09:30.000Z"
}
statusWhat it means
not_requestedThe call didn’t ask (record was false).
pendingIt will be recorded from the answer.
recordingIt’s being recorded now.
processingThe call is over and the file is being uploaded.
readyThe file is stored: get it.
skippedIt isn’t recorded. reason: workspace_off, all_party_state, or not_answered (nobody picked up).
failedIt couldn’t be kept. reason: upload_failed, or worker_lost (the listener never delivered it, or the notice couldn’t be said).
deletedYou 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. 503 storage_unavailable means the file store couldn’t be reached: nothing changed, try again.

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

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

{
"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"
}
}
}
FieldWhat it is
voicemailby (ai, rep or caller) and characters, or null. The words are on the call: voicemail.text.
summarysnippet (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.
recordingstatus (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, else null.
transcript.linesHow many finished lines the transcript has.
linksapi (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 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.

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()));
}
}
}

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 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 page before launch.