GuidesAPI EndpointsDiscussionsDevelopers BlogKnowledge BaseAppConnectTalkdeskContacts

Create/Duplicate Campaign

post https://api.talkdeskapp.com/campaigns

📘

Supported Regions and Base URLs

👍

Access and Registration

Authentication

Scopes

campaigns:read
campaigns:write

Request Body - Example

{
    "name": "test_create_campaign1",
    "priority": 5,
    "dialing_mode": "PREDICTIVE",
    "predictive_mode":
    {
        "answering_machine_detection": false,
        "amd_metadata": false,
        "max_abandonment_rate": 1,
        "max_dialing_ratio": 1,
        "max_ring_time_in_secs": 7,
        "abandonment_timeout":
        {
            "amount": 2
        }
    },
    "dialing_mode_configuration":
    {
        "answering_machine_detection": false,
        "amd_metadata": false,
        "max_abandonment_rate": 1,
        "max_dialing_ratio": 1,
        "max_ring_time_in_secs": 7,
        "abandonment_timeout":
        {
            "amount": 2
        }
    },
    "dialing_strategy":
    {
        "caller_ids":
        [],
        "calling_hours":
        [
            {
                "from": "2023-03-03T00:00:00.000Z",
                "to": "2023-03-02T12:00:00.000Z",
                "week_days":
                [
                    "MONDAY",
                    "TUESDAY",
                    "WEDNESDAY"
                ]
            }
        ],
        "dispositions":
        {
            "BUSY":
            {
                "status_after_call": "RETRY",
                "custom": false,
                "retry_time_unit": "MINUTES"
            },
            "NO_ANSWER":
            {
                "status_after_call": "RETRY",
                "custom": false,
                "retry_time_unit": "MINUTES"
            },
            "ABANDONMENT":
            {
                "status_after_call": "RETRY",
                "custom": false,
                "retry_time_unit": "MINUTES"
            },
            "HANGUP_BEFORE_CONNECTION":
            {
                "status_after_call": "RETRY",
                "custom": false,
                "retry_time_unit": "MINUTES"
            },
            "ANSWERING_MACHINE_DETECTION":
            {
                "status_after_call": "RETRY",
                "custom": false,
                "retry_time_unit": "MINUTES"
            },
            "INVALID_NUMBER":
            {
                "status_after_call": "FINAL",
                "custom": false,
                "retry_time_unit": "MINUTES"
            }
        },
        "ivr_enabled": false,
        "lists_sorting_criteria": "FIFO",
        "max_attempts": 1,
        "retry_period": 1,
        "retry_time_unit": "MINUTES"
    },
    "agents":
    []
}

Body Response - Schema

201 (campaign created successfully)

ParameterTypeDescriptionRequired
_linksobjectHAL API related links. "_links" subdivides into:

1 - "self" (object) - link to fetch the detail of the campaign.
1.1 - "href" (string) - address of the resource. <= 2083 characters.
Required.

2 - "campaigns" (object) - link to fetch a list of all the campaigns.
2.1 - "href" (string) - address of the resources.
<= 2083 characters.
Required.		yes
idstring<= 36 charactersyes
namestring>= 3 characters
<= 35 characters		yes
dialing_modestring<= 35 characters.
Allowed values: "PREDICTIVE", "PREVIEW"		no
priorityinteger>= 1
<= 10		no
run_oncebooleann/ano
action_requiredbooleann/ano
statusstring<= 35 characters.
Allowed values:
"INCOMPLETE", "READY",
"RUNNING", "PAUSED"		no
dialing_mode_configurationobject"dialing_mode_configuration" subdivides into:

1 - "answering_machine_detection" (boolean) - the flag to decide if disconnects calls that reach answering machines or voicemails.

2 - "max_abandonment_rate" (integer) - maximum rate of abandoned calls.
>= 1
<= 100

3 - "max_dialing_ratio
" (integer) - maximum number of calls launched per agent.
>= 1
<= 3

4 - "max_ring_time_in_secs
" (integer) - the time in which if the calls are not answered, they are disconnected.
>= 6
<= 120.
Required.

5 - "abandonment_timeout" (object)
5.1 - "amount
" (integer) - the time in which automatically hangs up answered calls that haven't been connected to an agent. Unit in seconds.
>= 2
<= 30
Required.		no
dialing_strategyobject"dialing_strategy" subdivides into:

1 - "max_skip_attempts" (integer) - the maximum number of times that an agent can skip a call.
>= 0
<= 20

2 - "strategy_type" (string) - the strategy on how the records will be dialed.
<= 35 characters
Allowed values:
"AUTOMATIC", "MANUAL"

3 - "preview_timeout" (integer) - the time in seconds that the preview context will be available to the agent.
>= 6
<= 300

4 - "max_attempts" (integer) - the maximum number of non-final call attempts each record may receive.
>= 1
<= 100.
Required.

5 - "retry_period" (integer) - time between non-final call attempts.
>= 1
<= 2592000.
Required.

6 - "retry_time_unit" (string) - the time unit for the retry_period.
<= 35 characters.
Allowed values: "SECONDS", "MINUTES",
"HOURS", "DAYS".
Required.

7 - "calling_hours" (array[object]) - set of rules to be applied based on location of the records lists. Required.
7.1 - "from" (string
 - start time format hh:MM:ss
<= 8 characters. Required.
7.2 - "to" (string
 - end time format hh:MM:ss
<= 8 characters. Required.
7.3 - "week_days" (array[string]) - Allowed values: "MONDAY",
"TUESDAY", "WEDNESDAY",
"THURSDAY", "FRIDAY",
"SATURDAY", "SUNDAY". Required.

8 - "dispositions (object) - system dispositions to be available for defined campaign. Required.
8.1 - "busy (object) - busy disposition settings. Required.
8.1.1 - "status_after_call (string) - <= 35 characters.
Allowed values: "FINAL",
"RETRY". Required.
8.1.2 - "custom (boolean) - required.
8.1.3 - "max_attempts (integer) - >= 1; <= 100.
8.1.4 - "retry_period (integer) - >= 1;
<= 2592000.
8.1.5 - "retry_period_time_unit (integer) - <= 35 characters.
Allowed values:
"SECONDS", "MINUTES",
"HOURS", "DAYS".

8.2 - "no_answer (object) - no_answer disposition settings. Required.
8.2.1 - "status_after_call (string) - <= 35 characters.
Allowed values: "FINAL",
"RETRY". Required.
8.2.2 - "custom (boolean) - required.
8.2.3 - "max_attempts (integer) - >= 1; <= 100.
8.2.4 - "retry_period (integer) - >= 1;
<= 2592000.
8.2.5 - "retry_period_time_unit (integer) - <= 35 characters.
Allowed values:
"SECONDS", "MINUTES",
"HOURS", "DAYS".

8.3 - "abandoned (object) - abandonment disposition settings.
8.3.1 - "status_after_call (string) - <= 35 characters.
Allowed values: "FINAL",
"RETRY". Required.
8.3.2 - "custom (boolean) - required.
8.3.3 - "max_attempts (integer) - >= 1; <= 100.
8.3.4 - "retry_period (integer) - >= 1;
<= 2592000.
8.3.5 - "retry_period_time_unit (integer) - <= 35 characters.
Allowed values:
"SECONDS", "MINUTES",
"HOURS", "DAYS".

8.4 - "hangup_before_connection (object) - hangup_before_connection disposition settings.
8.4.1 - "status_after_call (string) - <= 35 characters.
Allowed values: "FINAL",
"RETRY". Required.
8.4.2 - "custom (boolean) - required.
8.4.3 - "max_attempts (integer) - >= 1; <= 100.
8.4.4 - "retry_period (integer) - >= 1;
<= 2592000.
8.4.5 - "retry_period_time_unit (integer) - <= 35 characters.
Allowed values:
"SECONDS", "MINUTES",
"HOURS", "DAYS".

8.5 - "answering_machine_detection (object) - answering_machine_detection disposition settings.
8.5.1 - "status_after_call (string) - <= 35 characters.
Allowed values: "FINAL",
"RETRY". Required.
8.5.2 - "custom (boolean) - required.
8.5.3 - "max_attempts (integer) - >= 1; <= 100.
8.5.4 - "retry_period (integer) - >= 1;
<= 2592000.
8.5.5 - "retry_period_time_unit (integer) - <= 35 characters.
Allowed values:
"SECONDS", "MINUTES",
"HOURS", "DAYS".

8.6 - "invalid_number (object) - invalid_number disposition setting. Required.
8.6.1 - "status_after_call (string) - <= 35 characters.
Allowed value: "FINAL". Required.

9 - "record_chain (array[object]) -set of rules to be applied based on the phone type. Must have exactly one of each phone type.
9.1 - "type (string) - phone type. Allowed values: "HOME", "OFFICE", "MOBILE",
"EXTRA_1", "EXTRA_2"
"EXTRA_3". Required.
9.2 - "max_attempts (integer) - >= 1; <= 100. Required.
9.3 - "retry_period (integer) - >= 1;
<= 2592000.
9.4 - "retry_period_time_unit (integer) - the time unit for the retry_period.
Allowed values:
"SECONDS", "MINUTES",
"HOURS", "DAYS".

10 - "lists_sorting_criteria (string) - the configuration on how the records will be sorted.
<= 10 characters.
Allowed values: "FIFO",
"LIFO".		no
created_atstringn/ano

400 (errors found in the submitted data), 401 (unauthorized), 403 (forbidden)

ParameterTypeDescriptionRequired
codestringn/ayes
messagestringn/ayes
descriptionstringn/ano
fieldsarray[object]"fields" subdivides into:

"name" (string)

"description" (string)		yes (name and description)

❗️

API Availability

The Campaign Management API is only available for customers enrolled in Talkdesk's Early Access (EA) program.
To enter the EA program, contact a Customer Success Manager.

The Campaign Management APII has been in EA since November 2022.

🚧

Troubleshooting

If you have any questions regarding the usage of this API, or if you’re having any technical issues, please open a ticket using this form.

Language
Authorization
Header
Click Try It! to start a request and see the response here!