Taalk Help Center

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 no PATCH on campaigns, and there is no stop action: use cancel.

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

resetDNC can 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

  1. POST /campaign2s to create today's campaign, or reuse one.
  2. POST /campaign2s/{id}/contacts with { "append": [...] }. See API Guide: Contacts.
  3. POST /campaign2s/{id}/start with complianceAttested: true the first time.
  4. 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. Use POST.
  • Stop a campaign for good with one call. cancel ends the run; DELETE removes the campaign.