Campaigns

Create campaign

Creates the campaign and queues the import of the recipients. The campaign starts in import:waiting and moves on its own to schedule/processing when the import finishes and the start date arrives.

Use application/json when the recipients come from the contact base (type: connecta_contacts) and multipart/form-data when there is a file or an attachment. In multipart, the fields that are objects or lists (channel, queue, template, messages, mapping, tags, contacts, add_tags) go as JSON in text.

POST

campaigns

curl --request POST \
  --url https://api.connectadesk.com/api/v1/campaigns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "send_name": "Black Friday 2026",
  "slug": "black-friday-2026",
  "channel": {
    "id": 4
  },
  "type": "connecta_contacts",
  "import_contacts_mode": "tags",
  "tags": [
    7,
    12
  ],
  "tags_mode": "only",
  "tags_operator": "or",
  "message_type": "template",
  "template": {
    "name": "promocao_black_friday",
    "parameters": {
      "body": [
        "Maria",
        "30%"
      ]
    }
  },
  "init_timestamp": "2026-11-24T09:00:00.000Z",
  "send_avg_time": 30,
  "open_ticket": true,
  "queue": {
    "id": 7
  },
  "add_tags": [
    19
  ]
}
'

{
  "data": {
    "id": 77,
    "name": "Promoção de inverno",
    "status": "processing",
    "scheduledAt": "2026-08-19T12:00:00.000Z",
    "completedAt": null,
    "contactListId": 12,
    "channelId": 11,
    "createdAt": "2026-08-17T18:20:00.000Z",
    "updatedAt": "2026-08-19T12:00:03.221Z"
  }
}

{
  "error": {
    "code": "ERR_API_FORBIDDEN_SCOPE",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "ERR_API_VALIDATION",
    "message": "O parâmetro `application` é obrigatório e aceita \"contact\" ou \"card\"."
  }
}

Authorizations

Authorization

string

header

required

API token in the sk_live_… format.

Body

Campaign settings. Which fields are required depends on type (where the recipients come from) and message_type (what will be sent).

send_name

string

required

Campaign name, as it appears in the listing.

Example:

"Black Friday 2026"

slug

string

required

Short campaign identifier, used in reports.

Example:

"black-friday-2026"

channel

object

required

Outbound channel. See the available ones in GET /channels.

Show child attributes

type

enum<string>

required

Where the recipients come from: file (spreadsheet sent in the file field) or connecta_contacts (your contact base).

Available options:

file,

connecta_contacts

Example:

"connecta_contacts"

message_type

enum<string>

required

What will be sent: message (free text, unofficial channels only) or template (approved official WhatsApp template). Any other value returns 422 (ERR_API_CAMPAIGN_MESSAGE_TYPE_INVALID).

Available options:

message,

template

Example:

"template"

init_timestamp

string<date-time>

required

When the sending starts. It must be in the future.

Without a time zone, your company's time zone applies. 2026-11-24T09:00:00 starts at nine in the morning in the time zone set on the company — the same one you see in the panel. If you prefer to be explicit, send it with an offset (2026-11-24T09:00:00-03:00) or in UTC (2026-11-24T12:00:00.000Z), and the value is then respected as it is.

Example:

"2026-11-24T09:00:00-03:00"

send_avg_time

integer

required

Average interval between sends, in seconds. The longer it is, the slower and the safer for the number.

Example:

30

queue

object

required

Queue of the ticket the send creates. Required. It applies either way: with open_ticket: true the conversation opens already in that queue; without it, the ticket stays closed, but in the queue.

It is the queueId that decides where the ticket lands. Without a queue it would be created loose, showing up for no team — and you would only find out after the campaign ran. That is why creating or editing without queue responds 422 (ERR_API_CAMPAIGN_QUEUE_REQUIRED). See the queues in GET /queues.

Show child attributes

import_contacts_mode

enum<string>

Required with type: connecta_contacts. Picks contacts one by one or by tags.

Available options:

contacts,

tags

Example:

"tags"

contacts

integer[]

Contact ids, with import_contacts_mode: contacts. No file is needed: the list becomes the campaign's recipient base.

Every id must belong to this company — an id from outside returns 422 (ERR_API_CAMPAIGN_IDS_NOT_FOUND) with the list of what does not match.

Example:

[4821, 4822]

tags

integer[]

Tag ids, with import_contacts_mode: tags. The recipients are the contacts that match the tags, according to tags_mode and tags_operator. No file is needed here either, and the ids must belong to this company.

Example:

[7, 12]

tags_mode

enum<string>

How the tags filter the base: only (only those who have them), except (those who do not) or all (the whole base, ignoring the tags).

Available options:

all,

except,

only

Example:

"only"

tags_operator

enum<string>

With more than one tag: and requires all of them, or accepts any one of them.

Available options:

and,

or

Example:

"or"

mapping

object[]

Mapping between the spreadsheet columns and the system fields, with type: file.

Can be omitted. Without it, the mapping is built automatically from the header: each column is compared (ignoring accents and case) with the known names of each field — for example telefone, celular, whatsapp, fone, numero and phone become contact_number; nome, contato and cliente become contact_name; cpf, cnpj and documento become contact_cpfcnpj. For custom fields, the header is compared with the key and with the field name. A column that matches nothing comes in as dont_import, and the first column wins when two would point to the same field.

The phone and the name are required. If the automatic mapping does not recognize one of these columns, or if the mapping sent does not include contact_number and contact_name, creation returns 422 (ERR_API_CAMPAIGN_MAPPING_PHONE_REQUIRED or ERR_API_CAMPAIGN_MAPPING_NAME_REQUIRED) instead of creating a campaign that would fail on import.

Show child attributes

messages

string[]

Campaign texts, with message_type: message. More than one text makes the system alternate between them on each send. Accepts the contact variables ({{name}}, {{email}}…). The attachment of each message goes in message_attachment_<position>.

Example:

[
  "Olá {{name}}, temos uma novidade para você!"
]

template

object

Approved template, with message_type: template. Send only the name and the variables — the system builds the rest and checks it against the REAL templates of the channel, so a wrong name or a missing variable shows up here and not on the day of the send. See the available ones in GET /channels/{id}/templates.

Show child attributes

pause_timestamp

string<date-time>

Start of the daily pause window (for example, to avoid sending in the middle of the night). Same time zone rule as init_timestamp.

Example:

"2026-11-24T21:00:00-03:00"

restart_timestamp

string<date-time>

End of the pause window. Required when pause_timestamp is given. Same time zone rule as init_timestamp.

Example:

"2026-11-25T09:00:00-03:00"

open_ticket

boolean

Opens the ticket at the moment of the send: it comes in as pending in the queue queue and shows up for the agents right away. Without it the send goes out with the ticket closed, and the conversation only opens if the contact replies.

Example:

true

add_tags

integer[]

Tags applied to every contact the campaign reaches.

Example:

[19]

Response

Created

data

object

Show child attributes

Example:

{
  "id": 77,
  "name": "Promoção de inverno",
  "status": "processing",
  "scheduledAt": "2026-08-19T12:00:00.000Z",
  "completedAt": null,
  "contactListId": 12,
  "channelId": 11,
  "createdAt": "2026-08-17T18:20:00.000Z",
  "updatedAt": "2026-08-19T12:00:03.221Z"
}

curl --request POST \
  --url https://api.connectadesk.com/api/v1/campaigns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "send_name": "Black Friday 2026",
  "slug": "black-friday-2026",
  "channel": {
    "id": 4
  },
  "type": "connecta_contacts",
  "import_contacts_mode": "tags",
  "tags": [
    7,
    12
  ],
  "tags_mode": "only",
  "tags_operator": "or",
  "message_type": "template",
  "template": {
    "name": "promocao_black_friday",
    "parameters": {
      "body": [
        "Maria",
        "30%"
      ]
    }
  },
  "init_timestamp": "2026-11-24T09:00:00.000Z",
  "send_avg_time": 30,
  "open_ticket": true,
  "queue": {
    "id": 7
  },
  "add_tags": [
    19
  ]
}
'

{
  "data": {
    "id": 77,
    "name": "Promoção de inverno",
    "status": "processing",
    "scheduledAt": "2026-08-19T12:00:00.000Z",
    "completedAt": null,
    "contactListId": 12,
    "channelId": 11,
    "createdAt": "2026-08-17T18:20:00.000Z",
    "updatedAt": "2026-08-19T12:00:03.221Z"
  }
}

{
  "error": {
    "code": "ERR_API_FORBIDDEN_SCOPE",
    "message": "<string>",
    "details": "<unknown>"
  }
}

{
  "error": {
    "code": "ERR_API_VALIDATION",
    "message": "O parâmetro `application` é obrigatório e aceita \"contact\" ou \"card\"."
  }
}

Overview

Endpoints

Create campaign

Authorizations

Body

Response