Skip to navigation

Callbacks and number pools

Which number each rep call shows, how many calls each number makes a day, and where a prospect's call back rings.

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:

StrategyHow it picks
round_robin (default)The next number in turn.
local_presenceA 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:

StepRings
rep_browserThe 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_mobileThat rep’s mobile number (mobileNumber on the rep).
expertA Rydhm expert, which answers the call itself (set expertId).
voicemailVoicemail. 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:

unmatchedWhat 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_repIt 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, and as a webhook. Its externalRef is the call they’re calling back about, when Rydhm knows it.

Set it up

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);
}
Number settingValues
poolIdThe pool it’s in; null takes it out.
inboundModerep: calls to it ring the pool’s callback routing. expert (default): the number’s expert answers, as on any phone number.

Numbers themselves are bought or imported as usual: see Phone, Bring your own Twilio and Bring your own Telnyx.

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