API Guide: Campaigns
Create, update and run campaigns from your own systems. Base URL https://api.taalk.ai/api, header Authorization: Bearer <TAALK_API_KEY>. For keys, limits and errors, see API and Developer Access.
Updates use
POST /campaign2s/{id}. There is noPATCHon campaigns, and there is nostopaction: usecancel.
Campaign fields
These are the main fields. Each matches a setting on the campaign Settings tab.
| Field | Type | Setting in the console |
|---|---|---|
name |
string | Name (required) |
desc |
string | Internal Memo |
type |
number | Outreach Mode: 0 Voice-Only, 1 Multi-Channel, 2 Email-Only |
agent |
string | Outbound AI Agents (agent ID) |
host |
string | Caller ID Number: a number from Phone numbers, or a caller ID group path (starts with /) |
playbook |
string | Playbook (playbook ID) |
timezone |
number | Timezone, as a UTC offset in hours, for example -5 |
dailyStartTime / dailyEndTime |
{hour, minute} |
Start Time / End Time, in the campaign timezone |
maxRetry |
number | Max Retries (0 = unlimited) |
retryInterval |
number | Retry Interval, in hours |
limitPerHour |
number | Dials per Hour |
timeout |
number | Ring Timeout, in seconds |
currentTask |
object | The current run (read-only). status: 0 paused, 1 running, 2 canceled, 3 done |
contactCount |
number | Number of contacts (read-only) |
For what each setting does, see Campaign Scheduling, Retry and Stop Rules and Dialer Pacing.
List and read
curl "https://api.taalk.ai/api/campaign2s?active=true&page=0&pageSize=50" \
-H "Authorization: Bearer $TAALK_API_KEY"
| Parameter | What it does |
|---|---|
name |
Name contains this text (not case-sensitive) |
active |
true: only running campaigns. false: everything else |
page, pageSize |
Page from 0. Default page size is 10 |
The response is { "payload": [ ...campaigns ], "total": 28 }.
GET /campaign2s/{id} returns one campaign, including currentTask. Add fields=name,host,currentTask to return only some fields.
Create
curl -X POST https://api.taalk.ai/api/campaign2s \
-H "Authorization: Bearer $TAALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "June Renewals",
"type": 0,
"agent": "<AGENT_ID>",
"host": "<CALLER_ID_NUMBER>",
"timezone": -5,
"dailyStartTime": { "hour": 9, "minute": 0 },
"dailyEndTime": { "hour": 17, "minute": 0 },
"maxRetry": 3,
"retryInterval": 4,
"limitPerHour": 500,
"timeout": 20
}'
Returns 200 with the new campaign in payload. Save payload._id, then check the campaign in the console before you launch it.
Update
Send only the fields you want to change:
curl -X POST https://api.taalk.ai/api/campaign2s/<CAMPAIGN_ID> \
-H "Authorization: Bearer $TAALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "limitPerHour": 300, "dailyEndTime": { "hour": 19, "minute": 0 } }'
Each update is saved as a version in Version history, the same as a save in the console.
| Status | Why |
|---|---|
| 404 | Campaign not found |
| 409 | host is already used by another campaign. Free it first, or pick another caller ID |
| 424 | host is a caller ID group with no numbers |
Run a campaign
POST /campaign2s/{id}/{action}
| Action | What it does | Returns |
|---|---|---|
start |
Starts a new run. If the run is paused, it resumes it instead | 201 new run, 200 resumed |
pause |
Pauses dialing | 200, or 404 if not running |
resume |
Resumes a paused run | 200, or 404 if not running |
cancel |
Ends the run | 200, or 404 if not running |
restore |
Reopens the last canceled run | 200, or 406 if there is a current run or the last run wasn't canceled |
First start: confirm compliance
The first start of a campaign must include "complianceAttested": true. It confirms your contacts gave consent, your calling hours are right and your Do-Not-Call settings are reviewed. Taalk records who confirmed and when, the same as Before you launch in the console. Without it, the first start returns 400. Campaigns that already ran don't need it again.
curl -X POST https://api.taalk.ai/api/campaign2s/<CAMPAIGN_ID>/start \
-H "Authorization: Bearer $TAALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "complianceAttested": true, "stayAlive": true }'
See Launching a Campaign and Consent Management.
Start options
| Option | Console label | What it does |
|---|---|---|
stayAlive |
Keep Campaign Live | Keeps the run active, checking for new contacts and contacts due for a retry |
resetTry |
Reset Contact History | Resets attempt counts so contacts can be called again |
retryMissed |
Limits resetTry / resetDNC to contacts who never answered |
|
retryAnsweredWithoutAction |
Limits resetTry / resetDNC to contacts who answered but weren't transferred or texted |
|
resetDNC |
Clears the DNC flag on this campaign's contacts |
resetDNCcan put numbers that opted out back in the queue. Only use it when you know the flags are wrong. DNC Detection still applies.
Why a start fails
| Status | Why | Fix |
|---|---|---|
| 400 | No AI agent or caller ID (Voice-Only), empty caller ID group, or missing complianceAttested |
Set agent and host, or send complianceAttested: true |
| 409 | The campaign is already running | Nothing to do, or pause first |
| 428 | Auto-recharge is off | Turn on auto-recharge on the Subscription page |
| 429 | Your workspace has the maximum number of campaigns running | Pause or cancel another campaign |
Activity, segments and delete
| Method | Endpoint | What it does |
|---|---|---|
| GET | /campaign2s/{id}/activities |
The 100 most recent changes: who changed what, including status changes |
| POST | /campaign2s/segments |
Counts per filter. Body: { "running": { "active": true }, "renewals": { "name": "renewal" } }. Returns { "payload": { "running": 3, "renewals": 5 } }. A filter with no matches is left out |
| DELETE | /campaign2s/{id} |
Deletes the campaign and all its contacts, and cancels its run. Can't be undone |
Roles
Creating, updating and deleting campaigns needs the Admin User role. A User gets 401 "No access to modify the object." See User Management.
Example: daily refresh
POST /campaign2sto create today's campaign, or reuse one.POST /campaign2s/{id}/contactswith{ "append": [...] }. See API Guide: Contacts.POST /campaign2s/{id}/startwithcomplianceAttested: truethe first time.- Poll
GET /calls/status?campaign=<CAMPAIGN_ID>for live counts, or send results to your system with Event Webhooks.
Calls and messages from a campaign are charged to your balance. See How Billing Works.
What the Campaigns API can't do (yet)
- Partial updates with
PATCH. UsePOST. - Stop a campaign for good with one call.
cancelends the run;DELETEremoves the campaign.