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

# Sales calls in three steps

Sales calls let the people using your app call prospects from the browser while Rydhm listens: it writes down both sides, suggests what to ask next, leaves voicemails and writes up every call.

Before you start, in the Rydhm app under **Sales calls → Numbers**, switch on **Use for sales calls** for the number your calls come from (or get one). That's the only setup. You don't add reps: the person signed in to your app becomes one the first time their phone starts.

> **Note**
>
> Building an app other teams connect to, like a CRM? Give them a **Connect Rydhm** button instead of a key. See [Connect Rydhm](/developers/connect-with-rydhm).

#### Get a key

In **Developers → Sales calls**, click **Create a key for sales calls** (it has `calls:read` and `calls:write`). Put it on your server as `RYDHM_API_KEY`. Never in a web page.

#### Add two routes to your server

One route gives the signed-in person their phone. The other starts a call.

#### Add the phone to your page

`@rydhm/web` does the microphone, the ringing and the live suggestions. You draw the buttons.

## Step 2: your server

#### TypeScript

**`server.ts`**

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

const rydhm = new Rydhm(); // RYDHM_API_KEY

// The signed-in person's phone. The first time, Rydhm adds them as a rep (by your user id).
app.post("/api/rydhm/phone", requireUser, async (req, res) => {
  res.json(await rydhm.reps.softphoneToken(req.user.id, { name: req.user.name }));
});

// Start a call from that phone. Rydhm picks your number for sales calls.
app.post("/api/rydhm/call", requireUser, async (req, res) => {
  res.json(await rydhm.repCalls.create({ rep: req.user.id, to: req.body.to, suggestions: true }));
});
```

#### Python

**`server.py`**

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

client = Rydhm()  # RYDHM_API_KEY

@app.post("/api/rydhm/phone")  # the signed-in person's phone; the first time, they become a rep
@login_required
def phone():
    return client.reps.softphone_token(current_user.id, name=current_user.name).model_dump(by_alias=True)

@app.post("/api/rydhm/call")  # start a call; Rydhm picks your number for sales calls
@login_required
def call():
    return client.rep_calls.create(rep=current_user.id, to=request.json["to"], suggestions=True).model_dump(by_alias=True)
```

#### HTTP

```bash
# The person's phone (adds them as a rep the first time) → { url, token, presenceRoom, expiresAt }
curl -X POST https://api.rydhm.ai/v1/reps/usr_42/softphone-token \
  -H "Authorization: Bearer $RYDHM_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Asha Patel"}'

# Start a call from it → { id, status: "ringing", join: { url, token } }
curl -X POST https://api.rydhm.ai/v1/rep-calls \
  -H "Authorization: Bearer $RYDHM_API_KEY" -H "Content-Type: application/json" \
  -d '{"rep":"usr_42","to":"+14155550199","suggestions":true}'
```

`rep` can also be `{ "id": "usr_42", "name": "Asha Patel" }`: the rep is added (or their name updated) with the call itself. Send an `Idempotency-Key` header (your activity id) on `POST /v1/rep-calls` so a retry never dials twice.

## Step 3: your page

**`page.ts`**

```typescript title="page.ts"
import { Softphone } from "@rydhm/web";

const post = (url: string, body?: unknown) =>
  fetch(url, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) })
    .then((r) => r.json());
const getToken = () => post("/api/rydhm/phone");
const phone = new Softphone({ token: await getToken(), refreshToken: getToken });

callButton.onclick = async () => phone.join(await post("/api/rydhm/call", { to: prospect.phone }));
phone.on("suggestion", (s) => showTip(s.text)); // what to ask next
```

That's a working dialer. While the page is open, a prospect calling back rings it (`phone.on("incoming", …)`). See [Browser softphone](/engine/softphone).

## When something is missing

The API says what to fix in plain words:

| Error                         | What it means                                                                                                                                                                         |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `no_number` (400)             | No number is switched on for sales calls yet. Choose one in **Sales calls → Numbers**.                                                                                                |
| `pool_exhausted` (429)        | Every number for sales calls made its calls for today (80 each by default, so carriers don't mark them as spam). Add a number, or raise the daily limit under **Numbers → Advanced**. |
| `rep_not_found` (404)         | You started a call for someone whose phone never started. Send `rep` as `{ id, name }`, or `name` with the softphone token.                                                           |
| `outside_calling_hours` (400) | It's before 8 am or after 9 pm where the prospect is. `retryAt` says when you may call.                                                                                               |

## More

* **Voicemail and hang up**: when a machine answers, Rydhm can leave the voicemail for the person (`POST /v1/rep-calls/{id}/voicemail`). See [AI voicemail](/engine/ai-voicemail).
* **Call updates**: a webhook for `call.completed` and `call.summary.ready`, or one live stream per person. See [Rep calls](/engine/rep-calls#follow-the-call) and [Webhooks](/developers/webhooks).
* **Call records**: `GET /v1/rep-calls/{id}` and `GET /v1/rep-calls/{id}/transcript` once a call ends. See [Rep calls](/engine/rep-calls#after-the-call).