Skip to content

Campaign API

Run auto dialer campaigns from your CRM or backend: create a campaign on one of your agent groups, add phone numbers, start / pause / stop it, and read the result of every call.

When a campaign runs, the dialer places one call per free agent in the group: the customer and the agent are rung at the same time and connected once both have answered. A number that is not answered, busy, or fails — or is answered when no agent picked up in time — is called again 5 minutes later, up to 3 attempts in all. Every call is recorded.

Requires a Bearer API token (from Authentication / dashboard API Tokens) and the call-center permission.

Rate limit: 60 requests per minute per account, shared by all Campaign API endpoints.

  1. List Groups — pick the agent group. Its agents take the calls; its number is the caller ID.
  2. Create Campaign — with numbers, or empty. It starts as draft.
  3. Add Numbers — up to 1,000 per request, any time before the campaign is final.
  4. Start the campaign.
  5. Poll Call Results for new rows and Get Campaign for progress until status is completed.
Method Path Page
GET /api/cc/groups List Groups
POST /api/cc/campaigns Create Campaign
GET /api/cc/campaigns List Campaigns
GET /api/cc/campaigns/:id Get Campaign
POST /api/cc/campaigns/:id/contacts Add Numbers
POST /api/cc/campaigns/:id/start · /pause · /stop Start, Pause, Stop
GET /api/cc/campaigns/:id/calls Call Results
GET /api/cc/campaigns/:id/contacts List Numbers
Status Meaning
draft Created, never started
running Calling
paused No new calls; calls in progress finish. Start it again to continue
stopped Final. No new calls or numbers; numbers not called yet become cancelled
completed Final. Every number is done or out of attempts
Action Allowed from
start draft, paused
pause running
stop draft, running, paused
add numbers draft, running, paused

Only one campaign can run on a group at a time.

Campaign API errors return a message for people and a code for your code:

{
"error": "Another campaign is running on this group. Pause or stop it first.",
"code": "queue_busy"
}

Validation errors return 422 with an errors array instead.

Status Code Meaning
401 — Missing or invalid access token
403 — Account does not have the call-center permission
404 campaign_not_found Unknown campaign, or not on your account
409 invalid_status The action is not allowed in the campaign’s status
409 no_contacts Start needs at least one number not called yet
409 queue_busy Another campaign is running on this group
409 sender_has_no_trunk The group’s number cannot place calls; contact support
409 campaign_stopped · campaign_completed The campaign is already final
409 duplicate_request The same request_id was used within 15 minutes
422 group_not_eligible The group is not approved or has no number
422 no_valid_numbers None of the numbers is a valid Bangladesh mobile number
422 invalid_campaign The call engine refused the campaign settings
429 — Rate limit exceeded
503 engine_unreachable The call engine could not be reached; try again

Phone numbers must be Bangladesh mobile numbers (01XXXXXXXXX, +8801XXXXXXXXX and 8801XXXXXXXXX are accepted). Times are ISO 8601 with the Asia/Dhaka offset.