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.
- List Groups — pick the agent group. Its agents take the calls; its number is the caller ID.
- Create Campaign — with numbers, or empty. It starts as
draft. - Add Numbers — up to 1,000 per request, any time before the campaign is final.
- Start the campaign.
- Poll Call Results for new rows and Get Campaign for progress until
statusiscompleted.
Endpoints
Section titled “Endpoints”| 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 |
Statuses
Section titled “Statuses”| 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.
Errors
Section titled “Errors”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.
