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.
- 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 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:
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.
TypeScript
Python
HTTP
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):
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.
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:
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:
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:
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 }onGET /v1/rep-calls/{id}) and in the audit log, and thecall.completedwebhook carriescalling_hours_exception: { reason }(never the note). Inside the hours it’s ignored, andcallingHoursExceptionisnull. - Exceptions are on by default. A workspace admin can turn them off in Sales calls → Settings → Calling hours → Allow exceptions with a reason (
repCallHoursExceptionsin the workspace policies). Then any call that sends one gets403 hours_exception_not_allowed, andoutside_calling_hourssaysexceptionsAllowed: false.
TypeScript
Python
HTTP
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:
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.
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.
- Leave
suggestionsoff when you start the call. It’s off by default. - Read the call’s
call.transcriptevents and keep the finished lines from the prospect (final: true,speaker: "prospect"). - Give each one to your coach, and show its answer on the rep’s screen, where your app shows its cards.
TypeScript
Python
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.
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
Python
HTTP
The call.completed webhook tells you when the record is final.
Act 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:
- The
voicesent withPOST /v1/rep-calls/{id}/voicemail(that voicemail only). - The rep’s
voicemailVoice(PUT /v1/reps/{externalId}). - The workspace’s voice, set by an admin in Sales calls → Settings → Voicemail voice.
- 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):
- 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
+1number, 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:
- 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
readywithreason: "too_long". durationSeconds,bytesandreadyAtare set once it’sready.noticesays 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.
TypeScript
Python
HTTP
Live, and after the call
- During the call:
call.recordingwithstatus: "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 sendscall.recordingwithstatus: "skipped"and itsreasonon your server’s streams as soon as it starts. - After the call: the file is uploaded once the call ends, so the
call.completedwebhook usually saysrecording.status: "processing". Wait for thecall.recording.readywebhook, then get the link. Webhooks never carry a link to the file.call.recordingwithstatus: "ready"(orfailed) 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.
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.
TypeScript
Python
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.