Create a dialer campaign

curl --request POST \
  --url https://api.cloudtalk.io/v1/dialer/campaigns \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Q3 renewals",
  "mode": "sequential",
  "calling_policy": {
    "answer_wait": 25,
    "after_call": 10,
    "recording": true
  },
  "queue_policy": {
    "lock_size": 5,
    "refill_amount": 3
  },
  "retry_policy": {
    "max_attempts": 3,
    "interval_hours": 24
  },
  "waterfall_order": [
    "favorite",
    "rescheduled",
    "retry",
    "fresh"
  ],
  "agent_permissions": {
    "skip": true
  },
  "call_script_id": 310
}
'

import requests

url = "https://api.cloudtalk.io/v1/dialer/campaigns"

payload = {
    "name": "Q3 renewals",
    "mode": "sequential",
    "calling_policy": {
        "answer_wait": 25,
        "after_call": 10,
        "recording": True
    },
    "queue_policy": {
        "lock_size": 5,
        "refill_amount": 3
    },
    "retry_policy": {
        "max_attempts": 3,
        "interval_hours": 24
    },
    "waterfall_order": ["favorite", "rescheduled", "retry", "fresh"],
    "agent_permissions": { "skip": True },
    "call_script_id": 310
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Q3 renewals',
    mode: 'sequential',
    calling_policy: {answer_wait: 25, after_call: 10, recording: true},
    queue_policy: {lock_size: 5, refill_amount: 3},
    retry_policy: {max_attempts: 3, interval_hours: 24},
    waterfall_order: ['favorite', 'rescheduled', 'retry', 'fresh'],
    agent_permissions: {skip: true},
    call_script_id: 310
  })
};

fetch('https://api.cloudtalk.io/v1/dialer/campaigns', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cloudtalk.io/v1/dialer/campaigns",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Q3 renewals',
    'mode' => 'sequential',
    'calling_policy' => [
        'answer_wait' => 25,
        'after_call' => 10,
        'recording' => true
    ],
    'queue_policy' => [
        'lock_size' => 5,
        'refill_amount' => 3
    ],
    'retry_policy' => [
        'max_attempts' => 3,
        'interval_hours' => 24
    ],
    'waterfall_order' => [
        'favorite',
        'rescheduled',
        'retry',
        'fresh'
    ],
    'agent_permissions' => [
        'skip' => true
    ],
    'call_script_id' => 310
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cloudtalk.io/v1/dialer/campaigns"

	payload := strings.NewReader("{\n  \"name\": \"Q3 renewals\",\n  \"mode\": \"sequential\",\n  \"calling_policy\": {\n    \"answer_wait\": 25,\n    \"after_call\": 10,\n    \"recording\": true\n  },\n  \"queue_policy\": {\n    \"lock_size\": 5,\n    \"refill_amount\": 3\n  },\n  \"retry_policy\": {\n    \"max_attempts\": 3,\n    \"interval_hours\": 24\n  },\n  \"waterfall_order\": [\n    \"favorite\",\n    \"rescheduled\",\n    \"retry\",\n    \"fresh\"\n  ],\n  \"agent_permissions\": {\n    \"skip\": true\n  },\n  \"call_script_id\": 310\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cloudtalk.io/v1/dialer/campaigns")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Q3 renewals\",\n  \"mode\": \"sequential\",\n  \"calling_policy\": {\n    \"answer_wait\": 25,\n    \"after_call\": 10,\n    \"recording\": true\n  },\n  \"queue_policy\": {\n    \"lock_size\": 5,\n    \"refill_amount\": 3\n  },\n  \"retry_policy\": {\n    \"max_attempts\": 3,\n    \"interval_hours\": 24\n  },\n  \"waterfall_order\": [\n    \"favorite\",\n    \"rescheduled\",\n    \"retry\",\n    \"fresh\"\n  ],\n  \"agent_permissions\": {\n    \"skip\": true\n  },\n  \"call_script_id\": 310\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cloudtalk.io/v1/dialer/campaigns")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Q3 renewals\",\n  \"mode\": \"sequential\",\n  \"calling_policy\": {\n    \"answer_wait\": 25,\n    \"after_call\": 10,\n    \"recording\": true\n  },\n  \"queue_policy\": {\n    \"lock_size\": 5,\n    \"refill_amount\": 3\n  },\n  \"retry_policy\": {\n    \"max_attempts\": 3,\n    \"interval_hours\": 24\n  },\n  \"waterfall_order\": [\n    \"favorite\",\n    \"rescheduled\",\n    \"retry\",\n    \"fresh\"\n  ],\n  \"agent_permissions\": {\n    \"skip\": true\n  },\n  \"call_script_id\": 310\n}"

response = http.request(request)
puts response.read_body

{
  "id": "42",
  "name": "Q3 renewals",
  "mode": "sequential",
  "status": "initializing",
  "calling_policy": {
    "answer_wait": 25,
    "after_call": 10,
    "recording": true
  },
  "queue_policy": {
    "lock_size": 5,
    "refill_amount": 3
  },
  "retry_policy": {
    "max_attempts": 3,
    "interval_hours": 24
  },
  "schedule_policy": {
    "start_date": "2026-08-10",
    "start_time": "09:00"
  },
  "ttl_policy": {
    "mode": "campaign",
    "hours": 72
  },
  "waterfall_order": [
    "favorite",
    "rescheduled",
    "retry",
    "fresh"
  ],
  "agent_permissions": {
    "skip": true,
    "remove": false,
    "reorder": false
  },
  "call_script_id": "310",
  "survey_id": null,
  "created_at": "2026-08-01T09:15:00.000Z",
  "updated_at": "2026-08-01T09:15:00.000Z",
  "archived_at": null,
  "deleted_at": null
}

{
  "statusCode": 400,
  "message": "Validation error",
  "error": "Bad Request",
  "correlationId": "YevPQs",
  "subErrors": [
    "incorrect email"
  ]
}

{
  "code": "UNAUTHORIZED",
  "message": "You are not authorized to access this resource."
}

{
  "statusCode": 422,
  "message": "Unprocessable Entity",
  "error": "Unprocessable Entity",
  "correlationId": "YevPQs"
}

{
  "statusCode": 429,
  "message": "Too Many Requests",
  "error": "Too Many Requests",
  "correlationId": "YevPQs"
}

{
  "statusCode": 500,
  "message": "Internal Server Error",
  "error": "Internal Server Error",
  "correlationId": "YevPQs"
}

POST

dialer

campaigns

Create a dialer campaign

curl --request POST \
  --url https://api.cloudtalk.io/v1/dialer/campaigns \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Q3 renewals",
  "mode": "sequential",
  "calling_policy": {
    "answer_wait": 25,
    "after_call": 10,
    "recording": true
  },
  "queue_policy": {
    "lock_size": 5,
    "refill_amount": 3
  },
  "retry_policy": {
    "max_attempts": 3,
    "interval_hours": 24
  },
  "waterfall_order": [
    "favorite",
    "rescheduled",
    "retry",
    "fresh"
  ],
  "agent_permissions": {
    "skip": true
  },
  "call_script_id": 310
}
'

import requests

url = "https://api.cloudtalk.io/v1/dialer/campaigns"

payload = {
    "name": "Q3 renewals",
    "mode": "sequential",
    "calling_policy": {
        "answer_wait": 25,
        "after_call": 10,
        "recording": True
    },
    "queue_policy": {
        "lock_size": 5,
        "refill_amount": 3
    },
    "retry_policy": {
        "max_attempts": 3,
        "interval_hours": 24
    },
    "waterfall_order": ["favorite", "rescheduled", "retry", "fresh"],
    "agent_permissions": { "skip": True },
    "call_script_id": 310
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Q3 renewals',
    mode: 'sequential',
    calling_policy: {answer_wait: 25, after_call: 10, recording: true},
    queue_policy: {lock_size: 5, refill_amount: 3},
    retry_policy: {max_attempts: 3, interval_hours: 24},
    waterfall_order: ['favorite', 'rescheduled', 'retry', 'fresh'],
    agent_permissions: {skip: true},
    call_script_id: 310
  })
};

fetch('https://api.cloudtalk.io/v1/dialer/campaigns', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.cloudtalk.io/v1/dialer/campaigns",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Q3 renewals',
    'mode' => 'sequential',
    'calling_policy' => [
        'answer_wait' => 25,
        'after_call' => 10,
        'recording' => true
    ],
    'queue_policy' => [
        'lock_size' => 5,
        'refill_amount' => 3
    ],
    'retry_policy' => [
        'max_attempts' => 3,
        'interval_hours' => 24
    ],
    'waterfall_order' => [
        'favorite',
        'rescheduled',
        'retry',
        'fresh'
    ],
    'agent_permissions' => [
        'skip' => true
    ],
    'call_script_id' => 310
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.cloudtalk.io/v1/dialer/campaigns"

	payload := strings.NewReader("{\n  \"name\": \"Q3 renewals\",\n  \"mode\": \"sequential\",\n  \"calling_policy\": {\n    \"answer_wait\": 25,\n    \"after_call\": 10,\n    \"recording\": true\n  },\n  \"queue_policy\": {\n    \"lock_size\": 5,\n    \"refill_amount\": 3\n  },\n  \"retry_policy\": {\n    \"max_attempts\": 3,\n    \"interval_hours\": 24\n  },\n  \"waterfall_order\": [\n    \"favorite\",\n    \"rescheduled\",\n    \"retry\",\n    \"fresh\"\n  ],\n  \"agent_permissions\": {\n    \"skip\": true\n  },\n  \"call_script_id\": 310\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.cloudtalk.io/v1/dialer/campaigns")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Q3 renewals\",\n  \"mode\": \"sequential\",\n  \"calling_policy\": {\n    \"answer_wait\": 25,\n    \"after_call\": 10,\n    \"recording\": true\n  },\n  \"queue_policy\": {\n    \"lock_size\": 5,\n    \"refill_amount\": 3\n  },\n  \"retry_policy\": {\n    \"max_attempts\": 3,\n    \"interval_hours\": 24\n  },\n  \"waterfall_order\": [\n    \"favorite\",\n    \"rescheduled\",\n    \"retry\",\n    \"fresh\"\n  ],\n  \"agent_permissions\": {\n    \"skip\": true\n  },\n  \"call_script_id\": 310\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.cloudtalk.io/v1/dialer/campaigns")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Q3 renewals\",\n  \"mode\": \"sequential\",\n  \"calling_policy\": {\n    \"answer_wait\": 25,\n    \"after_call\": 10,\n    \"recording\": true\n  },\n  \"queue_policy\": {\n    \"lock_size\": 5,\n    \"refill_amount\": 3\n  },\n  \"retry_policy\": {\n    \"max_attempts\": 3,\n    \"interval_hours\": 24\n  },\n  \"waterfall_order\": [\n    \"favorite\",\n    \"rescheduled\",\n    \"retry\",\n    \"fresh\"\n  ],\n  \"agent_permissions\": {\n    \"skip\": true\n  },\n  \"call_script_id\": 310\n}"

response = http.request(request)
puts response.read_body

{
  "id": "42",
  "name": "Q3 renewals",
  "mode": "sequential",
  "status": "initializing",
  "calling_policy": {
    "answer_wait": 25,
    "after_call": 10,
    "recording": true
  },
  "queue_policy": {
    "lock_size": 5,
    "refill_amount": 3
  },
  "retry_policy": {
    "max_attempts": 3,
    "interval_hours": 24
  },
  "schedule_policy": {
    "start_date": "2026-08-10",
    "start_time": "09:00"
  },
  "ttl_policy": {
    "mode": "campaign",
    "hours": 72
  },
  "waterfall_order": [
    "favorite",
    "rescheduled",
    "retry",
    "fresh"
  ],
  "agent_permissions": {
    "skip": true,
    "remove": false,
    "reorder": false
  },
  "call_script_id": "310",
  "survey_id": null,
  "created_at": "2026-08-01T09:15:00.000Z",
  "updated_at": "2026-08-01T09:15:00.000Z",
  "archived_at": null,
  "deleted_at": null
}

{
  "statusCode": 400,
  "message": "Validation error",
  "error": "Bad Request",
  "correlationId": "YevPQs",
  "subErrors": [
    "incorrect email"
  ]
}

{
  "code": "UNAUTHORIZED",
  "message": "You are not authorized to access this resource."
}

{
  "statusCode": 422,
  "message": "Unprocessable Entity",
  "error": "Unprocessable Entity",
  "correlationId": "YevPQs"
}

{
  "statusCode": 429,
  "message": "Too Many Requests",
  "error": "Too Many Requests",
  "correlationId": "YevPQs"
}

{
  "statusCode": 500,
  "message": "Internal Server Error",
  "error": "Internal Server Error",
  "correlationId": "YevPQs"
}

The Dialer is a newly released product surface: depending on your account’s rollout stage, campaigns managed through this API may not yet be visible in your CloudTalk Dashboard.

Authorizations

Authorization

string

header

required

HTTP Basic Authentication. Use your API Access Key ID as the username and your API Access Key Secret as the password. Generate keys in the CloudTalk Dashboard under Account -> Settings -> API Keys (https://dashboard.cloudtalk.io/menu/account/settings/API-keys).

Body

application/json

Body of the campaign create call. Only name and mode are required; every policy bundle falls back to the service default when omitted.

name

string

required

Human-readable campaign name.

Maximum string length: 255

Example:

"Q3 renewals"

mode

enum<string>

required

Dialing mode. sequential dials one number at a time per agent; parallel dials several.

Available options:

sequential,

parallel

Example:

"sequential"

calling_policy

object

Per-call behaviour bundle. Every knob is optional — an omitted knob keeps the service default. Stored verbatim, so a bundle read back may also carry knobs added by a newer release.

Show child attributes

queue_policy

object

Allocation-batch and dynamic queue-sizing bundle. Every knob is optional.

Show child attributes

retry_policy

object

Re-dial rules bundle. Every knob is optional.

Show child attributes

schedule_policy

object

Campaign start-window bundle. Every knob is optional.

Show child attributes

ttl_policy

object

Contact-eligibility expiry bundle — drives how long an allocated contact stays held. Every knob is optional.

Show child attributes

waterfall_order

enum<string>[]

Ordered, duplicate-free subset of the waterfall categories. Contacts are served tier by tier in this order.

Available options:

favorite,

rescheduled,

retry,

fresh

Example:

["favorite", "rescheduled", "retry", "fresh"]

agent_permissions

object

Booleans gating what an agent may do to their queue. Deny by default — an omitted key is false.

Show child attributes

call_script_id

integer | null

Call script to link to the campaign; omit it or send null to create the campaign without a linked call script. Sent as an integer in requests; responses return the id as a string.

Required range: x >= 1

Example:

310

survey_id

integer | null

Survey to link to the campaign; omit it or send null to create the campaign without a linked survey. Sent as an integer in requests; responses return the id as a string.

Required range: x >= 1

Example:

44

Response

The created campaign.

A dialer campaign. Identifiers are returned as strings because they are 64-bit integers server-side.

string

Campaign ID.

Example:

"42"

name

string

Human-readable campaign name.

Example:

"Q3 renewals"

mode

enum<string>

Dialing mode.

Available options:

sequential,

parallel

Example:

"sequential"

status

enum<string>

Lifecycle status. initializing: created, membership backfill pending. active: the only dialable state. inactive: paused, fully reversible. archived: review/analytics state, not dialable, exits only back to inactive. deleted: soft-deleted, terminal.

Available options:

initializing,

active,

inactive,

archived,

deleted

Example:

"active"

calling_policy

object

Per-call behaviour bundle. Every knob is optional — an omitted knob keeps the service default. Stored verbatim, so a bundle read back may also carry knobs added by a newer release.

Show child attributes

queue_policy

object

Allocation-batch and dynamic queue-sizing bundle. Every knob is optional.

Show child attributes

retry_policy

object

Re-dial rules bundle. Every knob is optional.

Show child attributes

schedule_policy

object

Campaign start-window bundle. Every knob is optional.

Show child attributes

ttl_policy

object

Contact-eligibility expiry bundle — drives how long an allocated contact stays held. Every knob is optional.

Show child attributes

waterfall_order

enum<string>[]

Ordered, duplicate-free subset of the waterfall categories.

Available options:

favorite,

rescheduled,

retry,

fresh

Example:

["favorite", "rescheduled", "retry", "fresh"]

agent_permissions

object

Booleans gating what an agent may do to their queue. Deny by default — an omitted key is false.

Show child attributes

call_script_id

string | null

Linked call-script ID; null when none.

Example:

"310"

survey_id

string | null

Linked survey ID; null when none.

Example:

"44"

created_at

string<date-time>

Creation timestamp (ISO 8601, UTC).

Example:

"2026-08-01T09:15:00.000Z"

updated_at

string<date-time>

Last-update timestamp (ISO 8601, UTC).

Example:

"2026-08-04T11:42:07.000Z"

archived_at

string<date-time> | null

When the campaign entered archived; cleared on exit, so non-null only while the status is archived.

Example:

null

deleted_at

string<date-time> | null

Soft-delete timestamp; null unless the campaign has been deleted.

Example:

null

Overview

Endpoints

Create a dialer campaign

Authorizations

Body

Response