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

Criar e pré-visualizar campanha

Cria uma campanha de mensagem em massa por template e confere o tamanho do público antes de enviar.

Uma campanha (broadcast) envia o mesmo template aprovado pela Meta a um público. Você escolhe o template, as variáveis e o público; a plataforma resolve a lista de destinatários, remove quem não pode receber e a guarda. Depois é só enviar. Use primeiro a pré-visualização para ver quantas pessoas realmente receberão.

Pré-visualizar o público

Resolve o público sem criar nada. Devolve o total que casou e o total que realmente receberá depois dos filtros de consentimento e de quem pediu para parar. Pode ser chamada a cada mudança de filtro.

POST/api/v1/admin/whatsapp/broadcasts/previewAdmin

Conta quantas pessoas o público alcança e quantas receberão

Corpo da requisição

typestringobrigatório
all_customersusergrouplist_of_user_idsphone_listfilters
Tipo do público. Os demais campos do objeto de público ficam na raiz desta requisição.
usergroup_idstring
Com usergroup.
user_idsarray
Com list_of_user_ids.
phone_numbersarray
Com phone_list.
filtersobject
Com filters: tag, last_purchase_within_days, has_orders_count_min.

Exemplo de requisição (Pré-visualizar o público)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/broadcasts/preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "filters",
    "filters": {
      "last_purchase_within_days": 90,
      "has_orders_count_min": 2
    }
  }'

Resposta (Pré-visualizar o público)

200Contagem
json
{
  "matched_count": 1200,
  "will_send_count": 820,
  "marketing_optin_required": true
}

Campos da resposta

matched_countinteger
Pessoas que casam com o público, antes dos filtros.
will_send_countinteger
Pessoas que receberão: matched_count menos quem não deu consentimento (se a loja exige) e quem pediu para parar.
marketing_optin_requiredboolean
true quando a loja só envia a quem deu consentimento de marketing.

Erros (Pré-visualizar o público)

StatusQuandoCorpo
400Corpo inválido, type ausente ou desconhecido, ou usergroup_id ausente com usergroup.{"error":"audience.type required"}
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"}

Criar campanha

Resolve o público, aplica os filtros e grava a campanha com os destinatários. Por padrão fica em rascunho (R) e você chama a rota de envio. Com send_immediately, ela já entra em envio na mesma chamada. Não use send_immediately junto com scheduled_at.

POST/api/v1/admin/whatsapp/broadcastsAdmin

Cria uma campanha como rascunho, ou já a coloca em envio

Corpo da requisição

namestringobrigatório
Nome interno da campanha.
template_namestringobrigatório
Nome do template aprovado na Meta (veja Templates da Meta).
template_languagestring
Idioma do template, por exemplo pt_BR.
template_paramsobject
Variáveis como {"1":"...","2":"..."}. O mesmo valor vai para todos: não há personalização por destinatário.
scheduled_atstring
Quando começar, RFC 3339. Só vale depois de chamar o envio: uma campanha programada continua rascunho até você enviar.
audienceobjectobrigatório

Quem deve receber.

typestringobrigatório
all_customersusergrouplist_of_user_idsphone_listfilters
Como o público é escolhido.
usergroup_idstring
UUID do grupo de usuários. Obrigatório com usergroup.
user_idsarray
UUIDs de clientes, com list_of_user_ids.
phone_numbersarray
Telefones, com phone_list. Repetidos são descartados.
filtersobject

Critérios, com filters. Todos se combinam.

tagstring
Trecho do nome de um grupo de usuários (sem diferenciar maiúsculas).
last_purchase_within_daysinteger
Só quem comprou nos últimos N dias.
has_orders_count_mininteger
Só quem tem ao menos N pedidos.
send_immediatelybooleanpadrão: false
true cria e já coloca em envio.

Exemplo de requisição (Criar campanha)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/broadcasts" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Black Friday VIP",
    "template_name": "black_friday_vip",
    "template_language": "pt_BR",
    "template_params": {
      "1": "30%",
      "2": "30/11"
    },
    "audience": {
      "type": "filters",
      "filters": {
        "last_purchase_within_days": 90
      }
    },
    "send_immediately": false
  }'

Resposta (Criar campanha)

201Campanha criada
json
{
  "success": true,
  "broadcast": {
    "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": "R",
    "created_by": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
    "total_recipients": 820,
    "sent_count": 0,
    "delivered_count": 0,
    "read_count": 0,
    "failed_count": 0,
    "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"
  },
  "immediately_sent": false
}
202Criada, mas o envio imediato falhou
json
{
  "success": true,
  "broadcast": {
    "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": "R",
    "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"
  },
  "immediately_sent": false,
  "send_error": "whatsapp broadcast: cannot send in status ...",
  "send_error_message": "Broadcast saved as draft. Press Send in the detail view to retry."
}

Campos da resposta

successboolean
true.
broadcastobject

A campanha criada.

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.
immediately_sentboolean
true se já entrou em envio.
send_errorstring
Só no 202: o motivo de o envio imediato não ter ocorrido.

Erros (Criar campanha)

StatusQuandoCorpo
400Corpo inválido; name ou template_name ausente; audience.type ausente; erro ao resolver o público; send_immediately com scheduled_at (código whatsapp.broadcasts.send_now_with_schedule); ou send_immediately com público vazio (código whatsapp.broadcasts.empty_audience).{"error":"Failed to create broadcast: whatsapp broadcast: name and template_name required"}
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"}
Isto envia mensagens de verdade

Com send_immediately, ou ao chamar a rota de envio, cada destinatário recebe um template cobrado pela Meta. Confira o público com a pré-visualização e teste antes com uma lista de telefones só sua (phone_list).

Consentimento e 'parar'

Quem respondeu PARAR nunca recebe campanhas, sempre. Se a loja exige consentimento de marketing, quem não deu consentimento também fica de fora; telefones de uma lista que não pertencem a nenhum cliente cadastrado são tratados como sem consentimento. Os excluídos aparecem em skipped_count.

Veja também

  • Gerenciar campanhas
  • Templates da Meta
  • Templates gerenciados
Anterior
WhatsApp: campanhas
Próxima
Gerenciar campanhas
Nesta página
  • Pré-visualizar o público
  • Exemplo de requisição (Pré-visualizar o público)
  • Resposta (Pré-visualizar o público)
  • Erros (Pré-visualizar o público)
  • Criar campanha
  • Exemplo de requisição (Criar campanha)
  • Resposta (Criar campanha)
  • Erros (Criar campanha)
  • Veja também