Set Up a Predictive Dialer Campaign
Create a predictive dialer campaign with the SautiKit API, set the dial ratio and abandon target, handle waiting callers and tune the pacing.
Create a predictive dialer campaign with the SautiKit API, set the dial ratio and abandon target, handle waiting callers and tune the pacing.
A predictive dialer places more calls than there are free agents, because not every contact picks up. If your list answers one call in four, dialing exactly one number per free agent leaves agents listening to ringing most of the time. Dialing ahead keeps them talking.
SautiKit learns your list's answer rate from the campaign's own calls, hour by hour, and never has more than ratio_max calls out per free agent. When more people answer than there are agents, the extra caller hears a short hold line and is then sent to the next free agent, an AI agent or a callback offer. If that happens too often, the campaign lowers its own ratio.
Predictive dialing pays off for teams of about five agents or more working large, cold lists. For small teams, or lists where every answered caller must reach a person at once, use progressive dialing.
Every field, error and response is in the API reference.
dialer.write and dialer.read, numbers to call from, an extension per agent and a funded wallet.402 plan.required.Create a dialer campaign with mode set to predictive. Two settings control the pacing:
ratio_max: the most calls out per free agent, 1.0 to 3.0, default 1.5. With 4 free agents at 1.5, no more than 6 calls are ever out, so at most 2 answered callers can wait. At 1.0 the campaign behaves like progressive dialing.abandon_target_pct: the share of answered callers who may wait more than 2 seconds for an agent, default 3. The campaign slows down whenever it runs above this.For a new list, start with a ratio_max of 1.2 and raise it once you see the real answer rate.
const BASE = "https://api.sautikit.com";
const headers = {
Authorization: `Bearer ${process.env.SAUTIKIT_API_KEY}`,
"Content-Type": "application/json",
};
const campaign = await fetch(`${BASE}/v1/dialer/campaigns`, {
method: "POST",
headers,
body: JSON.stringify({
name: "Q4 loan offers",
mode: "predictive",
caller_ids: ["+254709000001", "+254709000002", "+254709000003"],
ratio_max: 1.2,
abandon_target_pct: 3,
budget_minor: 2500000,
daily_budget_minor: 500000,
hours: {
timezone: "Africa/Nairobi",
windows: [{ days: [1, 2, 3, 4, 5], start_minute: 540, end_minute: 1080 }],
},
retry: { max_attempts: 4, backoff_minutes: [60, 240, 1440], retry_on: ["no_answer", "busy"], ordering: "best_time" },
amd: { mode: "detect_and_act", on_machine: "hangup", max_analysis_seconds: 4 },
overflow: {
max_hold_ms: 2000,
hold_line_text: "Thanks for picking up. Someone will be with you in a moment.",
auto_ai: true,
ai_agent_id: process.env.SAUTIKIT_AI_AGENT_ID,
auto_ai_after_seconds: 8,
callback_enabled: true,
},
}),
}).then((r) => r.json());
console.log(campaign.id, campaign.mode, campaign.ratio_max); // predictive 1.2ordering: "best_time" dials the contacts most likely to answer at the current local hour first, and moves retries for hard-to-reach contacts to a better hour. Answering-machine detection matters more here than in any other mode: a machine that reaches an agent wastes the very time predictive dialing is meant to save.
When more people answer than there are free agents, the extra caller is never left in silence. The overflow settings set what they hear, in order:
max_hold_ms). Keep it at 2,000 ms or less, so a caller whose agent frees up quickly is never counted as abandoned.hold_line_text or a recording at hold_line_url).auto_ai with ai_agent_id), after auto_ai_after_seconds. AI minutes are billed as usual.callback_enabled): the caller presses 1 and is called back after callback_delay_minutes. Set callback_mode: "ai" to have an AI receptionist agree a time instead.A supervisor can also send one waiting caller to an AI agent by hand with hand off to AI.
These work exactly as in a progressive campaign: add contacts with an Idempotency-Key, then join each agent's extension, mark it ready and send a heartbeat every 30 seconds. The progressive guide has the code.
With no ready agent, a predictive campaign dials nothing.
curl -s "https://api.sautikit.com/v1/dialer/campaigns/$ID/estimate" \
-H "Authorization: Bearer $SAUTIKIT_API_KEY"
curl -s -X POST "https://api.sautikit.com/v1/dialer/campaigns/$ID/start" \
-H "Authorization: Bearer $SAUTIKIT_API_KEY"Starting spends money. Your budget, daily budget and the wallet balance are hard stops: when one runs out, no more calls are placed.
The live board and the dialer.stats frame on the event stream show how the pacing is doing:
| Field | What it tells you |
|---|---|
ratio | Calls out per free agent right now. Below ratio_max means the campaign has slowed itself down. |
answer_rate | People who answered over the last 100 dials. A low rate (0.1 to 0.2) means a cold list or a poor hour, and the campaign dials further ahead. |
abandon_rate_pct | The share of answered callers who waited more than 2 seconds for an agent. Compare it with abandon_target_pct. |
When the abandon rate runs above the target, the ratio drops by 10% and SautiKit sends a dialer.campaign.ratio_changed webhook. While the rate stays under half the target, the ratio creeps back up 2% at a time, never above ratio_max.
How to tune:
ratio_changed events, callers waiting: lower ratio_max to 1.2 or 1.3, add agents, or turn on overflow.auto_ai.ratio_max toward 2.0 and watch abandon_rate_pct.To change a setting, pause, update and resume. The campaign report gives the same figures for the whole run, with human_answer_rate, abandoned and the cost per connected call.
A predictive dialer is an outbound calling system that places more calls than there are free agents, using the expected answer rate to predict how many calls will be picked up. Agents spend their time talking instead of waiting through ringing and unanswered calls.
SautiKit defaults to 3%, meaning three answered callers in a hundred wait more than 2 seconds for an agent. Treat it as a tuning setting. Some markets regulate abandoned calls, so check the rules where your contacts live before you run predictive campaigns there.
For each free agent it estimates how many dials it takes to get one answer, from the campaign's own results in that hour of the day, and dials that many. It never has more than ratio_max calls out per free agent, and it lowers the ratio when too many callers wait.
A brief hold, a spoken line, and then whatever you set in overflow: an AI agent, a callback offer or a short apology. They never hear silence.
Yes. Pause the campaign, update mode to progressive or predictive, and resume. Contacts, attempts and agent sessions carry over.