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

# Callbacks and number pools

A **number pool** is a set of your workspace's phone numbers that rep calls go out from. It decides two things: which number a call shows to the prospect, and what happens when the prospect calls that number back.

## How a number is picked

Unless a call names its own `from`, Rydhm picks one from the pool:

| Strategy                | How it picks                                                                                                                               |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `round_robin` (default) | The next number in turn.                                                                                                                   |
| `local_presence`        | A number in the prospect's area code first, then one in the same US state, then the next in turn. People pick up local numbers more often. |

Each number makes at most **`dailyCapPerNumber`** calls a day (default 80, 1 to 1,000, counted in UTC). A number at its cap is skipped; when every number is, the call is refused with `429 pool_exhausted` (add numbers, or raise the cap). Spreading calls keeps each number's reputation healthy, so carriers are less likely to label it spam.

## Where callbacks ring

When someone calls a pool number back, the pool's **callback routing** rings, in order:

| Step          | Rings                                                                                                                                                                                                                               |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rep_browser` | The [softphone](/engine/softphone) of the rep who last called that person from that number, or else from any number of the same pool (people call back whichever number they have). When they're offline, routing moves on at once. |
| `rep_mobile`  | That rep's mobile number (`mobileNumber` on the rep).                                                                                                                                                                               |
| `expert`      | A Rydhm expert, which answers the call itself (set `expertId`).                                                                                                                                                                     |
| `voicemail`   | Voicemail. Always the last step when it's there.                                                                                                                                                                                    |

Each step rings for `ringSeconds` (5 to 60, default 20) before the next. The default order is `rep_browser`, `rep_mobile`, `voicemail`. When the rep **declines** in the browser, routing moves on at once. At the `expert` step the call becomes that expert's AI call from then on.

**Callers no rep has called** (a new lead calling in, someone calling from another phone) follow the pool's `unmatched` setting:

| `unmatched`        | What happens                                                                                                                                                                     |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `expert` (default) | The number's own expert answers, as on any phone number. With no expert on the number, the call isn't taken.                                                                     |
| `any_online_rep`   | It rings the rep who is online now (the one seen most recently), then goes on through the order above: their mobile, voicemail. With nobody online, the number's expert answers. |

The rep sees the callback as `incoming` in the softphone; your server sees `call.incoming` on the rep's [event stream](/engine/rep-calls#follow-the-call), and as a [webhook](/developers/webhooks#rep-calls-and-the-onboarding-coach). Its `externalRef` is the call they're calling back about, when Rydhm knows it.

## Set it up

#### TypeScript

```typescript
import { Rydhm } from "@rydhm/sdk";
const rydhm = new Rydhm(); // calls:write

const pool = await rydhm.numberPools.create({
  name: "West coast",
  strategy: "local_presence",
  dailyCapPerNumber: 60,
  callbackRouting: { order: ["rep_browser", "rep_mobile", "voicemail"], ringSeconds: 20, unmatched: "any_online_rep" },
});

// Then put numbers in it in the app (Sales calls -> Numbers), with incoming calls set to ring the
// pool's routing (inboundMode "rep"). From a signed-in admin session that is:
//   PATCH /v1/phone-numbers/{id} { poolId: pool.id, inboundMode: "rep" }  (API keys get 403 today)

// Follow one rep's callbacks from your server.
for await (const e of rydhm.events.stream({ repId: "usr_4821", types: ["call.incoming"] })) {
  console.log("Callback from", e.data.from, "about", e.data.externalRef);
}
```

#### Python

```python
from rydhm import Rydhm

client = Rydhm()

pool = client.number_pools.create(
    name="West coast",
    strategy="local_presence",
    daily_cap_per_number=60,
    callback_routing={"order": ["rep_browser", "rep_mobile", "voicemail"], "ringSeconds": 20, "unmatched": "any_online_rep"},
)
# Then put numbers in it in the app (Sales calls -> Numbers), with inbound mode "rep".

for event in client.events.stream(rep_id="usr_4821", types=["call.incoming"]):
    print("Callback from", event.data.from_, "about", event.data.external_ref)
```

| Number setting | Values                                                                                                                                           |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `poolId`       | The pool it's in; `null` takes it out.                                                                                                           |
| `inboundMode`  | `rep`: calls to it ring the pool's callback routing. `expert` (default): the number's expert answers, as on any [phone number](/channels/phone). |

Numbers themselves are bought or imported as usual: see [Phone](/channels/phone), [Bring your own Twilio](/channels/byo-twilio) and [Bring your own Telnyx](/channels/byo-telnyx).

> **Note**
>
> Pools themselves can be managed with a key (`calls:write`, from a key that isn't limited to some experts). **Moving a number into a pool** and setting its `inboundMode` stay in the app (**Sales calls** → **Numbers**) or a signed-in admin session, like every phone-number route: an API key gets `403 not_available_to_api_keys` from `PATCH /v1/phone-numbers/{id}`.