Pular para o conteúdo principal
As campanhas permitem enviar mensagens em massa para uma lista de contatos através de um canal do WhatsApp. Use os endpoints abaixo para criar, agendar e monitorar campanhas inteiramente a partir do seu próprio sistema. Todas as requisições exigem o cabeçalho Authorization: Bearer {BearerToken}.

Criar campanha

message1, message2 e message3 são variações aleatórias: cada contato recebe uma delas, escolhida aleatoriamente. Elas não são enviadas em sequência. Escrever o mesmo recado de três formas evita texto idêntico para todos e reduz o risco de bloqueio do número. A variável do nome do contato é {{name}}. Para canais WABA, use templateName e templateLanguage em vez dos campos de mensagem. Anexos de mídia devem ser adicionados através do painel após a criação da campanha; eles não podem ser definidos via API. O Carrossel (texto de abertura e cartões deslizáveis, cada um com imagem, texto e botões) também só é montado pelo painel, em Tipo de mensagem, nas conexões UazAPI: a campanha criada pela API nasce só com texto.

Adicionar contatos à campanha

Adicione um ou mais contatos a uma campanha. Você pode chamar este endpoint várias vezes para adicionar contatos de forma incremental.
O corpo aceita três formatos: um array de objetos com name e number (o contato é criado ou reaproveitado), um array de contatos existentes por ID ([{ "id": 1 }]) ou um objeto { "contactsIds": [1, 2, 3] }. A resposta traz added (quantos contatos entraram), contacts (lista com id e name) e skipped (os que não entraram).

Listar contatos de uma campanha

Retorna todos os contatos atualmente registrados na campanha. Cada contato traz campaignContacts com o estado do envio no campo ack: 0 = pendente, 1 ou mais = enviado, -1 = falha (os mesmos casos de falha de Obter relatório da campanha, com providerError quando houver).

Remover contato da campanha

Remove um único contato, identificado por contactId, da campanha.

Remover todos os contatos da campanha

Limpa toda a lista de contatos da campanha. Útil quando você deseja substituir a lista completamente antes do envio.

Listar campanhas

Esta rota não filtra por status. Para acompanhar uma campanha específica, use Obter relatório da campanha. Cada campanha da lista vem com contadores (contactsCount, pendentesEnvio, pendentesEntrega, recebidas e lidas), e a resposta traz a paginação em totalCount, totalPages, currentPage e limit. Contato com falha no envio (ack -1) conta só em contactsCount, fora de pendentesEnvio, pendentesEntrega, recebidas e lidas. Campanha com carrossel (montada pelo painel) vem com mediaType "carousel" e mediaUrl null; os cartões não vêm na listagem.

Iniciar campanha

Inicia o disparo de uma campanha. Inclua os contatos antes de iniciar.
A resposta é { "success": true, "data": { "campaignId": "123", "status": "started" } } (o campaignId vem como texto). Campanha com carrossel: antes de iniciar, o carrossel é conferido. Se ele não puder sair, a rota responde 400 com o motivo: Os cartões se corrigem pelo painel. Contato que é grupo não recebe carrossel: fica como falha no relatório e a campanha segue.
Iniciar respeita o horário de início (start). Se start estiver no futuro, a campanha passa para scheduled e aguarda esse horário. Para disparar imediatamente, atualize start para o horário atual com Atualizar campanha antes de iniciar.
Com a opção Verificar conversa em outros canais ativada (Configurações → Gerais → Geral), contatos que já estão em atendimento ou aguardando atendimento não recebem o envio da campanha.

Pausar campanha

Pausa uma campanha em andamento ou agendada: o status passa a paused. Com a campanha pausada, é possível editá-la com Atualizar campanha.

Retomar campanha pausada

Retoma uma campanha pausada. Se o horário de início (start) ainda estiver no futuro, a campanha volta para scheduled e aguarda esse horário. A campanha com carrossel pode ser pausada sozinha durante o envio: imagem de um cartão apagada ou trocada na galeria, canal trocado ou apagado, cartões inválidos, carrossel desligado, conexão do canal que não aceita o carrossel ou recusa o acesso (pausa já na primeira recusa) ou recusas seguidas do canal. O usuário dono da campanha recebe um aviso no painel. Ao retomar, ela passa pela mesma conferência de Iniciar campanha e pode responder 400 com ERR_CAMPAIGN_CAROUSEL_UNAVAILABLE, ERR_CAMPAIGN_CAROUSEL_CHANNEL, ERR_CAMPAIGN_CAROUSEL_INVALID ou ERR_CAMPAIGN_CAROUSEL_MEDIA_MISSING.

Cancelar campanha

Cancela uma campanha: o status passa a canceled e ela não dispara mais. Uma campanha cancelada ainda pode ser editada com Atualizar campanha. Para interromper só temporariamente, prefira pausar.

Pular contato atual da campanha

Pula o contato atual e avança para o próximo contato da campanha. Útil para destravar um disparo que ficou parado em um número problemático.
Nenhum corpo de requisição é necessário.
Só funciona com a campanha em processamento (processing). Fora disso (por exemplo, em scheduled), a rota responde 400 com { "error": "Campaign is not currently processing" }, sem o campo success.

Obter relatório da campanha

Obtenha estatísticas de entrega de uma campanha, incluindo quantas mensagens foram enviadas, entregues, lidas e que falharam.
A resposta traz status, start, channelType e os totais de envio (totalContacts, delivered, pending, failed e accepted, entre outros), além da lista contacts com a situação do envio para cada contato. Contato com falha vem com ack -1 e entra em failed (fora de delivered e accepted). Também contam como falha:
  • contato de campanha em canal oficial do WhatsApp sem template (templateName e templateLanguage);
  • contato de canal sem envio de campanha;
  • na campanha com carrossel, contato recusado pelo canal ou que é grupo (o carrossel não vai para grupos; providerError traz um texto JSON com code "carousel_group_not_supported").
Nesses casos, body e mediaName vêm "error". Na campanha com carrossel, body traz o texto de abertura enviado; os cartões não entram no relatório.

Atualizar campanha

Atualize a configuração de uma campanha existente.
Aceita os mesmos campos de Criar campanha. Campanha com carrossel (mediaType "carousel", montada pelo painel): message1, message2 e message3 são o texto de abertura, e os cartões só mudam pelo painel. mediaUrl e mediaType enviados no corpo são ignorados e ela continua carrossel. Trocar o sessionId para um canal que não envia carrossel responde 400 com ERR_CAMPAIGN_CAROUSEL_CHANNEL. Já mediaType "carousel" no corpo nunca transforma outra campanha em carrossel.
Você só pode atualizar uma campanha cujo status seja pending, scheduled, paused ou canceled. Tentar atualizar uma campanha no estado processing ou finished retorna um erro 404. O status não é editável por esta rota: use as rotas de iniciar, pausar, retomar ou cancelar campanha.

Duplicar campanha

Cria uma cópia de uma campanha existente. A cópia ganha id próprio, o nome original acrescido de - Copy, status pending e o mesmo start da original. O conteúdo das mensagens, as configurações e os contatos também são copiados. A cópia de uma campanha com carrossel leva os cartões; se o carrossel estiver desligado ou indisponível no servidor, a rota responde 409 com message "ERR_CAMPAIGN_CAROUSEL_UNAVAILABLE" e nada é criado.
Se o start da original já estiver próximo, ajuste o horário da cópia com Atualizar campanha ou exclua a cópia, para ela não disparar sozinha.
Para executar novamente uma campanha anterior com outra lista de contatos: duplique, remova todos os contatos da cópia, adicione a nova lista, ajuste o start e, em seguida, inicie.

Excluir campanha

Exclua permanentemente uma campanha e todos os seus dados associados.