Create a dialer campaign (draft)

Creates a draft drip-calling campaign. Nothing is dialed until POST .../start. caller_id must be an active number on this workspace. callback_url must be https to a public host: private, loopback, link-local and CGNAT addresses and localhost are refused (the same applies to a contact's own callback_url), and redirects from your endpoint are not followed. The 201 response carries callback_secret, the key that signs the answer callback: it is shown once, stored encrypted, and replaced with POST .../rotate-secret. Omitted settings take their defaults: 1 call per second, 20 concurrent, 3 attempts with 15 min / 2 h / 1 day backoff, AMD off. progressive and predictive modes need a plan that includes them (402 plan.required otherwise). A predictive campaign dials ahead of its free agents using the answer rate it learns from its own calls, never more than ratio_max calls per free agent (default 1.5), and slows itself down when answered callers wait (abandon_target_pct, default 3).

Authorization

bearerAuth

AuthorizationBearer <token>

Long-lived ES256 JWT minted from the dashboard (https://app.sautikit.com/developers/api-keys). Signed by the platform keyring. Carries workspace_id and scopes claims; revoked via the platform deny-list.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Length1 <= length <= 200

mode?string

Default"drip"

Value in

"drip"
"progressive"
"predictive"

caller_id?string

An active number on this workspace. Required to start (or send caller_ids).

caller_ids?array<string>

The numbers the campaign calls from, in order (1 to 10, each an active number on this workspace; duplicates collapse). Each call goes out from the one with the best recent answer rate; a number that keeps failing is only re-tested. caller_id is the first of them. Sending only caller_id sets a one-number list; sending both needs caller_id to equal the first of caller_ids.

Items1 <= items <= 10

callback_url?string

https URL on a public host (private, loopback and link-local addresses and localhost are refused) that receives the answer callback. Required to start.

Formaturi

release_rate_per_sec?number

Range0.01 <= value <= 10

Default1

max_concurrent?integer

Range1 <= value <= 200

Default20

hours?

When calls may be released. No windows means unrestricted apart from blackout dates.

timezone?string

Default"Africa/Nairobi"

retry?

budget_minor?integer

Total spend cap in minor currency units.

Formatint64

Range0 <= value

daily_budget_minor?integer

Formatint64

Range0 <= value

warn_pct?integer

Range1 <= value <= 100

Default80

amd?

Answering-machine detection, billed per token spent at the platform token price.

overflow?

What a caller meets when they answer and no agent is free: a brief hold, one spoken hold line, then (if configured) an AI agent, a callback offer and an apology. Never silence. Send any subset; the rest keeps its value.

summary?

Post-call summary and suggested outcome (off by default). Only calls with a transcript are summarised, which today means calls an AI agent took (an overflow hand-off); a call a person answered has none. A PATCH replaces the whole summary object.

ratio_max?number

Predictive only: the most calls the pacing engine may have out per free agent. 1.0 is progressive. The abandon controller lowers the working ratio below this when too many answered callers wait; it never raises it above.

Range1 <= value <= 3

Default1.5

abandon_target_pct?number

Predictive only: the abandon percentage the controller holds the campaign to (a tuning knob, not a legal claim). An abandoned call is a person who answered and was not connected to an agent within 2 seconds.

Range0.1 <= value <= 10

Default3

Response Body

`application/json`

curl -X POST "https://example.com/v1/dialer/campaigns" \  -H "Content-Type: application/json" \  -d '{    "name": "October reminders",    "caller_id": "+254709221583",    "callback_url": "https://example.com/dialer/answered",    "release_rate_per_sec": 1,    "max_concurrent": 20,    "budget_minor": 500000,    "hours": {      "timezone": "Africa/Nairobi",      "windows": [        {          "days": [            1,            2,            3,            4,            5          ],          "start_minute": 540,          "end_minute": 1020        }      ]    },    "retry": {      "max_attempts": 3,      "backoff_minutes": [        15,        120,        1440      ],      "retry_on": [        "no_answer",        "busy",        "failed"      ]    },    "amd": {      "mode": "detect_and_act",      "on_machine": "hangup",      "max_analysis_seconds": 4    }  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "name": "string",  "status": "draft",  "mode": "drip",  "caller_id": "string",  "caller_ids": [    "string"  ],  "callback_url": "string",  "release_rate_per_sec": 0,  "max_concurrent": 0,  "hours": {    "timezone": "string",    "windows": [      {        "days": [          0        ],        "start_minute": 0,        "end_minute": 1      }    ],    "blackouts": [      "2019-08-24"    ]  },  "timezone": "string",  "retry": {    "max_attempts": 1,    "backoff_minutes": [      0    ],    "retry_on": [      "no_answer"    ],    "min_gap_minutes": 0,    "ordering": "fifo"  },  "budget_minor": 0,  "daily_budget_minor": 0,  "warn_pct": 0,  "spent_minor": 0,  "amd": {    "mode": "off",    "on_machine": "hangup",    "max_analysis_seconds": 4,    "machine_message": "string"  },  "overflow": {    "max_hold_ms": 2000,    "hold_line_seconds": 10,    "auto_ai": false,    "auto_ai_after_seconds": 0,    "ai_agent_id": "cbaf6aba-437a-4fd2-9d34-7875f81689e6",    "callback_enabled": true,    "callback_delay_minutes": 10,    "callback_mode": "keypad",    "callback_agent_id": "01422de9-87cc-4157-b531-8850ef02c157",    "callback_prompt": "string",    "hold_line_text": "string",    "hold_line_url": "http://example.com",    "callback_offer_text": "string",    "callback_confirm_text": "string",    "apology_text": "string"  },  "summary": {    "enabled": false,    "engine": "extractive"  },  "ratio_max": 0,  "ratio_current": 0,  "abandon_target_pct": 0,  "started_at": "2019-08-24T14:15:22Z",  "completed_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z",  "estimate": {    "contacts": 0,    "max_attempts": 0,    "telco_minor": 0,    "amd_minor": 0,    "total_minor": 0,    "currency": "string",    "budget_minor": 0,    "exceeds_budget": true,    "priced": true  },  "callback_secret": "string"}

{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254727524723"  }}

{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254727524723"  }}

{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254727524723"  }}

{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ],    "resolution": "string",    "reason": "invalid_characters",    "suggested_e164": "+254727524723"  }}

Create a dialer campaign (draft)

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

402application/json

403application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`