Skip to main content
POST
/
api
/
campaigns
curl -X POST https://api.disparador.com/api/campaigns \
  -H "Content-Type: application/json" \
  -H "X-Access-Token: seu-access-token" \
  -d '{
    "name": "Campanha de Natal",
    "evolutionUrl": "https://evolution-api.exemplo.com",
    "evolutionApiKey": "sua-api-key",
    "evolutionInstance": "whatsapp-01",
    "contacts": [
      {
        "phoneNumber": "11999999999",
        "name": "João"
      },
      {
        "phoneNumber": "11888888888",
        "name": "Maria"
      }
    ],
    "message": "Olá {PrimeiroNome}! Feliz Natal! 🎄"
  }'
{
  "id": 123,
  "name": "Campanha de Natal",
  "description": null,
  "status": "ACTIVE",
  "type": "TEXT",
  "createdAt": "2024-01-20T10:30:00",
  "scheduledFor": null,
  "totalContacts": 2,
  "sentContacts": 0,
  "failedContacts": 0,
  "pendingContacts": 2,
  "progressPercentage": 0,
  "successRate": 0,
  "messageContent": "Olá {PrimeiroNome}! Feliz Natal! 🎄",
  "mediaType": null,
  "mediaUrl": null,
  "fileName": null,
  "evolutionInstance": "whatsapp-01",
  "minInterval": 3,
  "maxInterval": 5,
  "notificationPhone": null,
  "pollData": null,
  "evolutionConfig": {
    "id": 1,
    "name": "WhatsApp Principal",
    "url": "https://evolution-api.exemplo.com",
    "instance": "whatsapp-01"
  },
  "message": null
}
Cria uma nova campanha de disparo de mensagens via WhatsApp. Suporta texto, mídia (imagem, vídeo, áudio, documento), enquetes e agendamento.
Você precisa de um access token válido no header X-Access-Token para usar este endpoint.
Filtro Automático de Contatos Bloqueados: Os contatos que estão na lista de bloqueados serão automaticamente removidos da campanha antes do envio. O campo blockedContactsRemoved no response indica quantos contatos foram filtrados.

Headers

Content-Type
string
required
application/json
X-Access-Token
string
required
Token de acesso obtido no login

Body

Informações Básicas

name
string
required
Nome da campanha (obrigatório)
isTest
boolean
default:"false"
Se true, marca a campanha como teste
isDraft
boolean
default:"false"
Se true, salva a campanha como rascunho sem enviar

Configuração Evolution API

evolutionUrl
string
required
URL completa da sua Evolution API (ex: https://evolution-api.exemplo.com)
evolutionApiKey
string
required
API Key da sua Evolution API
evolutionInstance
string
required
Nome da instância do WhatsApp conectada
evolutionConfigId
number
ID de uma configuração Evolution salva (alternativa aos campos acima)

Contatos

contacts
array
required
Lista de contatos que receberão a mensagem

Conteúdo da Mensagem

message
string
Conteúdo da mensagem. Obrigatório exceto quando usando enquetes ou salvando como rascunho.Suporta variáveis:
  • {PrimeiroNome} - Primeiro nome do contato
  • {NomeCompleto} - Nome completo do contato

Mídia (Opcional)

mediaUrl
string
URL do arquivo de mídia ou dados em base64URL: https://exemplo.com/imagem.jpgBase64: data:image/jpeg;base64,/9j/4AAQSkZJRg…
mediaType
string
Tipo de mídia. Se não fornecido, será detectado automaticamente.
  • image: JPG, PNG, GIF
  • video: MP4, 3GP
  • audio: MP3, OGG, AAC
  • document: PDF, DOC, XLS, etc
fileName
string
Nome do arquivo (recomendado para base64 e documentos)
caption
string
Legenda para imagens e vídeos (máximo 1024 caracteres)

Enquete (Opcional)

pollData
object
Dados da enquete. Quando fornecido, substitui a necessidade de message.

Agendamento (Opcional)

scheduledFor
string
Data e hora para agendamento no formato: YYYY-MM-DDTHH:mmExemplos:
  • 2024-12-25T10:00 (formato aceito)
  • 2024-12-25T10:00:00 (também aceito)
Mínimo: 5 minutos no futuro

Configurações de Envio

intervalMinSeconds
number
Intervalo mínimo entre mensagens em segundos
intervalMaxSeconds
number
Intervalo máximo entre mensagens em segundos
notificationPhone
string
Número para receber notificação quando a campanha for concluída

Configurações Avançadas

databaseConfigId
number
ID da configuração de banco de dados para variáveis personalizadas
curl -X POST https://api.disparador.com/api/campaigns \
  -H "Content-Type: application/json" \
  -H "X-Access-Token: seu-access-token" \
  -d '{
    "name": "Campanha de Natal",
    "evolutionUrl": "https://evolution-api.exemplo.com",
    "evolutionApiKey": "sua-api-key",
    "evolutionInstance": "whatsapp-01",
    "contacts": [
      {
        "phoneNumber": "11999999999",
        "name": "João"
      },
      {
        "phoneNumber": "11888888888",
        "name": "Maria"
      }
    ],
    "message": "Olá {PrimeiroNome}! Feliz Natal! 🎄"
  }'
JavaScript
const campaignData = {
  name: "Campanha de Natal",
  evolutionUrl: "https://evolution-api.exemplo.com",
  evolutionApiKey: "sua-api-key",
  evolutionInstance: "whatsapp-01",
  contacts: [
    {
      phoneNumber: "11999999999",
      name: "João"
    },
    {
      phoneNumber: "11888888888",
      name: "Maria"
    }
  ],
  message: "Olá {PrimeiroNome}! Feliz Natal! 🎄",
  intervalMinSeconds: 3,
  intervalMaxSeconds: 5
};

const response = await fetch('https://api.disparador.com/api/campaigns', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Access-Token': 'seu-access-token'
  },
  body: JSON.stringify(campaignData)
});

const result = await response.json();
if (result.id) {
  console.log(`Campanha criada com ID: ${result.id}`);
  console.log(`Status: ${result.status}`);
  console.log(`Total de contatos: ${result.totalContacts}`);
} else {
  console.error('Erro:', result.message);
}
Python
import requests
import json

url = "https://api.disparador.com/api/campaigns"
headers = {
    'Content-Type': 'application/json',
    'X-Access-Token': 'seu-access-token'
}

# Campanha com mídia
data = {
    "name": "Campanha com Vídeo",
    "evolutionUrl": "https://evolution-api.exemplo.com",
    "evolutionApiKey": "sua-api-key",
    "evolutionInstance": "whatsapp-01",
    "contacts": [
        {
            "phoneNumber": "11999999999",
            "name": "Cliente"
        }
    ],
    "message": "Assista ao vídeo sobre nossos produtos!",
    "mediaUrl": "https://exemplo.com/video.mp4",
    "mediaType": "video",
    "caption": "Conheça nossa nova linha de produtos",
    "intervalMinSeconds": 5,
    "intervalMaxSeconds": 10
}

response = requests.post(url, headers=headers, json=data)
result = response.json()

if response.status_code == 200:
    print(f"Campanha criada: ID {result['id']}")
    print(f"Status: {result['status']}")
    print(f"Total de contatos: {result['totalContacts']}")
else:
    print(f"Erro: {result['message']}")
PHP
<?php
$url = 'https://api.disparador.com/api/campaigns';
$headers = [
    'Content-Type: application/json',
    'X-Access-Token: seu-access-token'
];

// Campanha com enquete
$data = [
    'name' => 'Pesquisa de Satisfação',
    'evolutionUrl' => 'https://evolution-api.exemplo.com',
    'evolutionApiKey' => 'sua-api-key',
    'evolutionInstance' => 'whatsapp-01',
    'contacts' => [
        [
            'phoneNumber' => '11999999999',
            'name' => 'Cliente'
        ]
    ],
    'pollData' => [
        'name' => 'Como você avalia nosso atendimento?',
        'options' => ['Excelente', 'Bom', 'Regular', 'Ruim'],
        'selectableCount' => 1
    ]
];

$options = [
    'http' => [
        'header' => implode("\r\n", $headers),
        'method' => 'POST',
        'content' => json_encode($data)
    ]
];

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$response = json_decode($result, true);

if (isset($response['id'])) {
    echo "Campanha criada com ID: " . $response['id'] . "\n";
    echo "Status: " . $response['status'] . "\n";
} else {
    echo "Erro: " . $response['message'] . "\n";
}
?>

Response

Campos Principais

id
number
ID único da campanha criada
name
string
Nome da campanha
description
string
Descrição da campanha
status
string
Status atual da campanha
  • DRAFT - Rascunho
  • SCHEDULED - Agendada
  • ACTIVE - Em execução
  • PAUSED - Pausada
  • COMPLETED - Concluída
  • CANCELLED - Cancelada
  • FAILED - Falhou
type
string
Tipo da campanha (TEXT, MEDIA, POLL)
createdAt
string
Data/hora de criação
scheduledFor
string
Data/hora de agendamento (se aplicável)

Estatísticas

totalContacts
number
Total de contatos na campanha
sentContacts
number
Quantidade de mensagens já enviadas
failedContacts
number
Quantidade de envios que falharam
pendingContacts
number
Quantidade de contatos pendentes
progressPercentage
number
Percentual de progresso (0-100)
successRate
number
Taxa de sucesso em percentual

Dados da Campanha

messageContent
string
Conteúdo da mensagem da campanha
mediaType
string
Tipo de mídia anexada (se houver)
mediaUrl
string
URL da mídia anexada
fileName
string
Nome do arquivo de mídia
evolutionInstance
string
Instância Evolution usada
minInterval
number
Intervalo mínimo entre mensagens
maxInterval
number
Intervalo máximo entre mensagens
notificationPhone
string
Telefone para notificação
pollData
object
Dados da enquete (quando aplicável)
evolutionConfig
object
Configuração Evolution completa usada
message
string
Mensagem de erro (apenas em caso de falha)
{
  "id": 123,
  "name": "Campanha de Natal",
  "description": null,
  "status": "ACTIVE",
  "type": "TEXT",
  "createdAt": "2024-01-20T10:30:00",
  "scheduledFor": null,
  "totalContacts": 2,
  "sentContacts": 0,
  "failedContacts": 0,
  "pendingContacts": 2,
  "progressPercentage": 0,
  "successRate": 0,
  "messageContent": "Olá {PrimeiroNome}! Feliz Natal! 🎄",
  "mediaType": null,
  "mediaUrl": null,
  "fileName": null,
  "evolutionInstance": "whatsapp-01",
  "minInterval": 3,
  "maxInterval": 5,
  "notificationPhone": null,
  "pollData": null,
  "evolutionConfig": {
    "id": 1,
    "name": "WhatsApp Principal",
    "url": "https://evolution-api.exemplo.com",
    "instance": "whatsapp-01"
  },
  "message": null
}

Validações

  • Nome: Obrigatório
  • Mensagem: Obrigatória (exceto para enquetes ou rascunhos)
  • Contatos: Pelo menos 1 contato válido
  • Enquete: 2-10 opções únicas, máximo 100 caracteres cada
  • Agendamento: Mínimo 5 minutos no futuro
  • Evolution API: Credenciais válidas e instância conectada

Limites

  • Contatos por campanha: Sem limite definido (recomendado até 10.000)
  • Tamanho da mensagem: 4096 caracteres
  • Tamanho da legenda: 1024 caracteres
  • Nome da enquete: 280 caracteres
  • Opções de enquete: 2-10 opções, máximo 100 caracteres cada
  • Arquivo de mídia: Depende dos limites do WhatsApp

Variáveis de Personalização

Você pode usar as seguintes variáveis nas mensagens:
  • {PrimeiroNome} - Primeiro nome do contato
  • {NomeCompleto} - Nome completo do contato
Suporta variáveis de personalização:
Olá {PrimeiroNome}!

Seu nome completo {NomeCompleto} foi selecionado para uma oferta especial.

Webhooks

A campanha enviará notificações via webhook nos seguintes eventos:
  • campaign.started - Quando a campanha iniciar
  • campaign.progress - A cada 10% de progresso
  • campaign.completed - Quando finalizar
  • campaign.failed - Se falhar
Configure o webhook no painel de configurações da empresa.
I