Campaigns

Manage campaigns and add contacts to campaigns

List Campaigns

get

Get all campaigns for the organization. Optionally filter by status.

Authorizations

OrganizationApiToken

AuthorizationstringRequired

Organization API Token.

Paste only your token in the field below — the Bearer prefix is added automatically by the docs UI and in every generated code sample. The final header sent is:

Authorization: Bearer {orgId}.{secretToken}

Token format: {orgId}.{secretToken} — example: 15c94c3c-1873-4a09-bfbb-03357c29ea50.abc123xyz.

JWT tokens are NOT accepted.

Query parameters

limitintegerOptional

Number of results to return (default: 50)

offsetintegerOptional

Offset for pagination (default: 0)

statusstringOptional

Filter by status (active, paused, stopped, completed, draft)

Responses

200

List of campaigns

application/json

Other propertiesanyOptional

get/api/campaigns

HTTPcURLJavaScriptPython

GET /api/campaigns HTTP/1.1
Host: api.agentalk.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

List of campaigns

{
  "campaigns": [
    {
      "campaignId": "c1a2m3p4-a5i6-7890-abcd-ef1234567890",
      "name": "Summer Sale Campaign",
      "status": "active",
      "audienceSource": "CSV",
      "startedAt": "2025-01-01T08:00:00Z",
      "endAt": "2025-01-31T23:59:59Z",
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Create Campaign

post

Create a new outbound campaign in draft status. Activate it afterwards with POST /api/campaigns/{campaignId}/start, and add contacts with POST /api/campaigns/{campaignId}/contacts.

Only name is required. The campaign timezone is always taken from the organization settings and cannot be set here. maxParallelCalls may not exceed the concurrent-call limit of the organization's current plan.

Authorizations

OrganizationApiToken

AuthorizationstringRequired

Organization API Token.

Paste only your token in the field below — the Bearer prefix is added automatically by the docs UI and in every generated code sample. The final header sent is:

Authorization: Bearer {orgId}.{secretToken}

Token format: {orgId}.{secretToken} — example: 15c94c3c-1873-4a09-bfbb-03357c29ea50.abc123xyz.

JWT tokens are NOT accepted.

Body

application/json

namestringRequired

Campaign name (required)

Example: Summer Sale Campaign

voicebotIdstring · uuidOptional

Voicebot UUID used for outbound calls

Example: v1o2i3c4-e5b6-7890-abcd-ef1234567890

phoneNumberIdsinteger[]Optional

Phone number integration IDs to dial from (from GET /api/account/phone-numbers). Empty = use all voicebot numbers.

Example: [12,15]

fromDatestring · date-timeOptional

Campaign window start (ISO 8601)

Example: 2026-06-20T08:00:00Z

toDatestring · date-timeOptional

Campaign window end (ISO 8601)

Example: 2026-07-20T20:00:00Z

startTimestringOptional

Daily call window start time (HH:MM, in the organization timezone)

Example: 09:00

endTimestringOptional

Daily call window end time (HH:MM, in the organization timezone)

Example: 18:00

maxParallelCallsintegerOptional

Max concurrent calls (must not exceed plan limit)

Example: 3

maxAttemptsPerContactintegerOptional

Max dial attempts per contact

Example: 3

retryIntervalMinutesintegerOptional

Minutes to wait before retrying a failed call

Example: 30

campaignGoalstring · enumOptional

Campaign goal (optional)

Example: lead_goalPossible values:

Responses

201

Campaign created (draft)

application/json

Other propertiesanyOptional

400

Validation error (e.g. maxParallelCalls exceeds plan limit)

application/json

post/api/campaigns

HTTPcURLJavaScriptPython

POST /api/campaigns HTTP/1.1
Host: api.agentalk.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 378

{
  "name": "Summer Sale Campaign",
  "voicebotId": "v1o2i3c4-e5b6-7890-abcd-ef1234567890",
  "phoneNumberIds": [
    12,
    15
  ],
  "fromDate": "2026-06-20T08:00:00Z",
  "toDate": "2026-07-20T20:00:00Z",
  "startTime": "09:00",
  "endTime": "18:00",
  "activeDays": [
    "monday",
    "tuesday",
    "wednesday",
    "thursday",
    "friday"
  ],
  "maxParallelCalls": 3,
  "maxAttemptsPerContact": 3,
  "retryIntervalMinutes": 30,
  "campaignGoal": "lead_goal"
}

{
  "campaign": {
    "campaignId": "c1a2m3p4-a5i6-7890-abcd-ef1234567890",
    "name": "Summer Sale Campaign",
    "status": "active",
    "audienceSource": "CSV",
    "startedAt": "2025-01-01T08:00:00Z",
    "endAt": "2025-01-31T23:59:59Z",
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-01T00:00:00Z"
  }
}

Add Contacts to Campaign

post

Add one or more contacts to a campaign. Returns summary of added, reset (already in campaign, status reset), and invalid contacts.

Use contacts to set an optional per-contact follow-up time (followUpAt, ISO 8601). The dialer will not call the contact before that time. contactIds (plain ID array, no follow-up) is still supported for backward compatibility; at least one of the two fields is required.

Authorizations

OrganizationApiToken

AuthorizationstringRequired

Organization API Token.

Paste only your token in the field below — the Bearer prefix is added automatically by the docs UI and in every generated code sample. The final header sent is:

Authorization: Bearer {orgId}.{secretToken}

Token format: {orgId}.{secretToken} — example: 15c94c3c-1873-4a09-bfbb-03357c29ea50.abc123xyz.

JWT tokens are NOT accepted.

Path parameters

campaign_idstring · uuidRequired

Campaign ID

Body

application/json

contactIdsstring[]Optional

Array of contact IDs to add (no follow-up). Provide this or contacts.

Example: ["con_1","con_2"]

Responses

200

Summary of operation

application/json

Other propertiesanyOptional

post/api/campaigns/{campaign_id}/contacts

HTTPcURLJavaScriptPython

POST /api/campaigns/{campaign_id}/contacts HTTP/1.1
Host: api.agentalk.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 125

{
  "contacts": [
    {
      "contactId": "con_1",
      "followUpAt": "2026-06-15T09:00:00Z"
    },
    {
      "contactId": "con_2"
    }
  ],
  "contactIds": [
    "con_1",
    "con_2"
  ]
}

200

Summary of operation

{
  "added": 2,
  "reset": 0,
  "invalid": 0,
  "invalidIds": []
}

Start Campaign

post

Start (activate) a campaign. Optionally schedule it for a future time.

Authorizations

OrganizationApiToken

AuthorizationstringRequired

Organization API Token.

Paste only your token in the field below — the Bearer prefix is added automatically by the docs UI and in every generated code sample. The final header sent is:

Authorization: Bearer {orgId}.{secretToken}

Token format: {orgId}.{secretToken} — example: 15c94c3c-1873-4a09-bfbb-03357c29ea50.abc123xyz.

JWT tokens are NOT accepted.

Path parameters

campaign_idstring · uuidRequired

Campaign ID

Body

application/json

startAtstring · date-timeOptional

ISO 8601 timestamp to schedule start (optional)

Example: 2025-11-27T08:00:00Z

Responses

200

Campaign started successfully

application/json

Other propertiesanyOptional

post/api/campaigns/{campaign_id}/start

HTTPcURLJavaScriptPython

POST /api/campaigns/{campaign_id}/start HTTP/1.1
Host: api.agentalk.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 34

{
  "startAt": "2025-11-27T08:00:00Z"
}

200

Campaign started successfully

{
  "campaign": {
    "campaignId": "c1a2m3p4-a5i6-7890-abcd-ef1234567890",
    "name": "Summer Sale Campaign",
    "status": "active",
    "audienceSource": "CSV",
    "startedAt": "2025-01-01T08:00:00Z",
    "endAt": "2025-01-31T23:59:59Z",
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-01T00:00:00Z"
  }
}