VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/WhatsApp: campanhas

Gerenciar campanhas

Lista campanhas, consulta o andamento, dispara o envio e cancela.

Depois de criada, uma campanha segue um ciclo curto. O envio não é instantâneo: um processo em segundo plano pega as campanhas em envio (respeitando scheduled_at) e as despeja numa fila de mensagens, que a plataforma esvazia no ritmo permitido pela Meta. Por isso sent_count sobe aos poucos.

Listar campanhas

Devolve uma página de campanhas com os contadores de cada uma.

GET/api/v1/admin/whatsapp/broadcastsAdmin

Lista as campanhas, as mais novas primeiro

Parâmetros de consulta

statusstring
RPAD
Filtra pela letra do estado: R, P, A ou D. Os nomes por extenso (draft, sending...) não funcionam: devolvem lista vazia.
pageintegerpadrão: 1
Página.
per_pageintegerpadrão: 25
Itens por página, de 1 a 200. Fora disso vale 25.

Exemplo de requisição (Listar campanhas)

bash
curl "$BASE_URL/api/v1/admin/whatsapp/broadcasts?status=P" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Listar campanhas)

200Campanhas
json
{
  "broadcasts": [
    {
      "id": "f0fb5296-bc6b-46a8-a772-f5d5a78627fd",
      "name": "Black Friday VIP",
      "template_name": "black_friday_vip",
      "template_language": "pt_BR",
      "template_params": {
        "1": "30%",
        "2": "30/11"
      },
      "status": "P",
      "created_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
      "started_at": "2026-10-11T22:00:00Z",
      "total_recipients": 820,
      "sent_count": 400,
      "delivered_count": 380,
      "read_count": 210,
      "failed_count": 5,
      "skipped_count": 130,
      "audience": {
        "type": "filters",
        "filters": {
          "last_purchase_within_days": 90
        }
      },
      "created_at": "2026-10-11T21:50:00Z",
      "updated_at": "2026-10-11T22:05:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 25,
  "total_pages": 1
}

Campos da resposta

broadcastsarray

Campanhas da página.

idstring
UUID da campanha.
namestring
Nome interno.
template_namestring
Template da Meta usado.
template_languagestring
Idioma do template, por exemplo pt_BR.
template_paramsobject
Variáveis do template, iguais para todos os destinatários.
statusstring
RPAD
Situação como letra: R rascunho, P enviando (também usada para enfileirada), A concluída, D cancelada.
created_bystring
UUID de quem criou.
scheduled_atstring
Início programado, RFC 3339. Ausente se não foi programada.
started_atstring
Quando entrou em envio.
finished_atstring
Quando terminou ou foi cancelada.
total_recipientsinteger
Destinatários que vão receber (já sem os excluídos).
sent_countinteger
Mensagens entregues à Meta.
delivered_countinteger
Entregues no aparelho.
read_countinteger
Lidas.
failed_countinteger
Falhas.
skipped_countinteger
Excluídos por falta de consentimento ou por terem pedido para parar.
audienceobject
O seletor de público usado, guardado para auditoria.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração.
totalinteger
Total.
pageinteger
Página.
per_pageinteger
Itens por página.
total_pagesinteger
Páginas.

Erros (Listar campanhas)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
O estado é uma letra

status sai como R, P, A ou D, e o filtro compara a letra. A mesma letra P serve para "na fila" e "enviando".

Consultar uma campanha

Os campos da campanha vêm na raiz, e recipient_counts resume os destinatários por situação.

GET/api/v1/admin/whatsapp/broadcasts/{id}Admin

Devolve a campanha com a contagem de destinatários por situação

Parâmetros de caminho

idstringobrigatório
UUID da campanha.

Exemplo de requisição (Consultar uma campanha)

bash
curl "$BASE_URL/api/v1/admin/whatsapp/broadcasts/f0fb5296-bc6b-46a8-a772-f5d5a78627fd" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Consultar uma campanha)

200Campanha
json
{
  "id": "f0fb5296-bc6b-46a8-a772-f5d5a78627fd",
  "name": "Black Friday VIP",
  "template_name": "black_friday_vip",
  "template_language": "pt_BR",
  "template_params": {
    "1": "30%",
    "2": "30/11"
  },
  "status": "P",
  "created_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "started_at": "2026-10-11T22:00:00Z",
  "total_recipients": 820,
  "sent_count": 400,
  "delivered_count": 380,
  "read_count": 210,
  "failed_count": 5,
  "skipped_count": 130,
  "audience": {
    "type": "filters",
    "filters": {
      "last_purchase_within_days": 90
    }
  },
  "created_at": "2026-10-11T21:50:00Z",
  "updated_at": "2026-10-11T22:05:00Z",
  "recipient_counts": {
    "pending": 420,
    "queued": 0,
    "sent": 400,
    "delivered": 0,
    "read": 0,
    "failed": 5,
    "skipped": 0
  }
}

Campos da resposta

(...)object
Todos os campos da listagem.
recipient_countsobject

Destinatários por situação.

pendinginteger
Aguardando.
queuedinteger
Na fila.
sentinteger
Enviados.
deliveredinteger
Entregues.
readinteger
Lidos.
failedinteger
Falhas.
skippedinteger
Excluídos.

Erros (Consultar uma campanha)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
404Campanha inexistente.{"error":"broadcast not found"}
Confie nos contadores da campanha

Em recipient_counts, os destinatários entregues, lidos e excluídos gravados em letra (V, R, K) não são somados em delivered, read e skipped, que ficam em 0 mesmo quando houve entrega. Para o funil, use delivered_count, read_count e skipped_count da própria campanha.

Enviar a campanha

Passa um rascunho para envio. O processo em segundo plano assume a partir daí. É idempotente: chamar de novo numa campanha que já está enviando devolve sucesso sem fazer nada. Concluída ou cancelada não pode ser enviada. Sem corpo.

POST/api/v1/admin/whatsapp/broadcasts/{id}/sendAdmin

Coloca a campanha em envio

Parâmetros de caminho

idstringobrigatório
UUID da campanha.

Exemplo de requisição (Enviar a campanha)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/broadcasts/f0fb5296-bc6b-46a8-a772-f5d5a78627fd/send" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Enviar a campanha)

200Em envio
json
{
  "success": true
}

Campos da resposta

successboolean
true.

Erros (Enviar a campanha)

StatusQuandoCorpo
400Campanha inexistente, ou em estado que não permite envio (concluída ou cancelada).{"error":"Failed to send broadcast: whatsapp broadcast: cannot send in status \"A\""}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
Dispara mensagens reais

Não há desfazer para o que já saiu. Para parar o restante, use cancelar.

Cancelar a campanha

Vale para rascunho e campanha em envio. O que já foi enviado não volta; os destinatários ainda pendentes deixam de ser processados. Sem corpo.

POST/api/v1/admin/whatsapp/broadcasts/{id}/cancelAdmin

Cancela uma campanha que ainda não terminou

Parâmetros de caminho

idstringobrigatório
UUID da campanha.

Exemplo de requisição (Cancelar a campanha)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/broadcasts/f0fb5296-bc6b-46a8-a772-f5d5a78627fd/cancel" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Cancelar a campanha)

200Cancelada
json
{
  "success": true
}

Campos da resposta

successboolean
true.

Erros (Cancelar a campanha)

StatusQuandoCorpo
400Campanha inexistente ou já concluída/cancelada.{"error":"Failed to cancel broadcast: whatsapp broadcast: not cancellable in current state"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}

Veja também

  • Criar campanha
  • Mensagens enviadas
Anterior
Criar e pré-visualizar campanha
Próxima
Templates da Meta
Nesta página
  • Listar campanhas
  • Exemplo de requisição (Listar campanhas)
  • Resposta (Listar campanhas)
  • Erros (Listar campanhas)
  • Consultar uma campanha
  • Exemplo de requisição (Consultar uma campanha)
  • Resposta (Consultar uma campanha)
  • Erros (Consultar uma campanha)
  • Enviar a campanha
  • Exemplo de requisição (Enviar a campanha)
  • Resposta (Enviar a campanha)
  • Erros (Enviar a campanha)
  • Cancelar a campanha
  • Exemplo de requisição (Cancelar a campanha)
  • Resposta (Cancelar a campanha)
  • Erros (Cancelar a campanha)
  • Veja também