Campanhas

Criar campanha

Cria a campanha e coloca a importação dos destinatários na fila. A campanha nasce em import:waiting e passa sozinha para schedule/processing quando a importação termina e a data de início chega.

Use application/json quando os destinatários vêm da base (type: connecta_contacts) e multipart/form-data quando há arquivo ou anexo. No multipart, os campos que são objeto ou lista (channel, queue, template, messages, mapping, tags, contacts, add_tags) vão como JSON em texto.

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\"."
  }
}

Autorizações

Authorization

string

header

obrigatório

Token da API no formato sk_live_….

Corpo

Configuração da campanha. Os campos obrigatórios variam com type (de onde vêm os destinatários) e message_type (o que será enviado).

send_name

string

obrigatório

Nome da campanha, como aparece na listagem.

Exemplo:

"Black Friday 2026"

slug

string

obrigatório

Identificador curto da campanha, usado nos relatórios.

Exemplo:

"black-friday-2026"

channel

object

obrigatório

Canal de saída. Veja os disponíveis em GET /channels.

Show child attributes

type

enum<string>

obrigatório

De onde vêm os destinatários: file (planilha enviada no campo file) ou connecta_contacts (base de contatos).

Opções disponíveis:

file,

connecta_contacts

Exemplo:

"connecta_contacts"

message_type

enum<string>

obrigatório

O que será enviado: message (texto livre, só em canal não oficial) ou template (template aprovado do WhatsApp oficial). Outro valor responde 422 (ERR_API_CAMPAIGN_MESSAGE_TYPE_INVALID).

Opções disponíveis:

message,

template

Exemplo:

"template"

init_timestamp

string<date-time>

obrigatório

Quando o disparo começa. Precisa ser no futuro.

Sem fuso, vale o fuso da sua empresa. 2026-11-24T09:00:00 dispara às nove da manhã no fuso configurado na empresa — que é o que você vê no painel. Se preferir ser explícito, mande com fuso (2026-11-24T09:00:00-03:00) ou em UTC (2026-11-24T12:00:00.000Z), e aí o valor é respeitado como está.

Exemplo:

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

send_avg_time

integer

obrigatório

Intervalo médio entre os envios, em segundos. Quanto maior, mais lento e mais seguro para o número.

Exemplo:

30

queue

object

obrigatório

Fila do atendimento que o disparo cria. Obrigatória. Vale nos dois casos: com open_ticket: true a conversa abre já nessa fila; sem ele, o atendimento fica fechado, mas na fila.

É o queueId que decide onde o atendimento entra. Sem fila ele nasceria solto, sem aparecer para nenhum time — e você só descobriria depois da campanha rodar. Por isso criar ou editar sem queue responde 422 (ERR_API_CAMPAIGN_QUEUE_REQUIRED). Veja as filas em GET /queues.

Show child attributes

import_contacts_mode

enum<string>

Obrigatório com type: connecta_contacts. Escolhe contatos um a um ou por tags.

Opções disponíveis:

contacts,

tags

Exemplo:

"tags"

contacts

integer[]

Ids dos contatos, com import_contacts_mode: contacts. Não precisa enviar arquivo: a lista vira a base de destinatários da campanha.

Todos os ids precisam ser desta empresa — um id de fora responde 422 (ERR_API_CAMPAIGN_IDS_NOT_FOUND) com a lista do que não confere.

Exemplo:

[4821, 4822]

tags

integer[]

Ids das tags, com import_contacts_mode: tags. Os destinatários são os contatos que casam com as tags, conforme tags_mode e tags_operator. Também não precisa de arquivo, e os ids precisam ser desta empresa.

Exemplo:

[7, 12]

tags_mode

enum<string>

Como as tags filtram a base: only (só quem tem), except (quem não tem) ou all (toda a base, ignorando as tags).

Opções disponíveis:

all,

except,

only

Exemplo:

"only"

tags_operator

enum<string>

Com mais de uma tag: and exige todas, or aceita qualquer uma.

Opções disponíveis:

and,

or

Exemplo:

"or"

mapping

object[]

De-para entre as colunas da planilha e os campos do sistema, com type: file.

Pode ser omitido. Sem ele, o de-para é montado automaticamente a partir do cabeçalho: cada coluna é comparada (sem acento e sem diferenciar maiúsculas) com os nomes conhecidos de cada campo — por exemplo telefone, celular, whatsapp, fone, numero e phone viram contact_number; nome, contato e cliente viram contact_name; cpf, cnpj e documento viram contact_cpfcnpj. Para os campos personalizados, o cabeçalho é comparado com a key e com o nome do campo. Coluna que não casa com nada entra como dont_import, e a primeira coluna vence quando duas apontariam para o mesmo campo.

Telefone e nome são obrigatórios. Se o automático não reconhecer uma dessas colunas, ou se o mapping enviado não tiver contact_number e contact_name, a criação responde 422 (ERR_API_CAMPAIGN_MAPPING_PHONE_REQUIRED ou ERR_API_CAMPAIGN_MAPPING_NAME_REQUIRED) em vez de criar uma campanha que falharia na importação.

Show child attributes

messages

string[]

Textos da campanha, com message_type: message. Mais de um texto faz o sistema alternar entre eles a cada disparo. Aceita as variáveis do contato ({{name}}, {{email}}…). O anexo de cada mensagem vai em message_attachment_<posição>.

Exemplo:

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

template

object

Template aprovado, com message_type: template. Informe só o nome e as variáveis — o sistema monta o restante e confere contra os templates REAIS do canal, então um nome errado ou uma variável faltando aparece aqui e não no dia do disparo. Consulte os disponíveis em GET /channels/{id}/templates.

Show child attributes

pause_timestamp

string<date-time>

Início da janela de pausa diária (por exemplo, para não disparar de madrugada). Mesma regra de fuso do init_timestamp.

Exemplo:

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

restart_timestamp

string<date-time>

Fim da janela de pausa. Obrigatório quando pause_timestamp é informado. Mesma regra de fuso do init_timestamp.

Exemplo:

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

open_ticket

boolean

Abre a conversa no momento do disparo: o atendimento entra como pending na fila de queue e já aparece para os atendentes. Sem isso o disparo sai com o atendimento fechado, e a conversa só abre se o contato responder.

Exemplo:

true

add_tags

integer[]

Tags aplicadas a cada contato que a campanha atinge.

Exemplo:

[19]

Resposta

Criado

data

object

Show child attributes

Exemplo:

{
  "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\"."
  }
}

Visão geral

Endpoints

Criar campanha

Autorizações

Corpo

Resposta