WhatsApp: campanhas

Mensagens em massa por WhatsApp: público, campanhas, envio e templates da Meta.

Campanhas são mensagens em massa por WhatsApp: a loja escolhe um template aprovado pela Meta, define o público e a plataforma envia a todos, respeitando consentimento e pedidos de descadastro. Esta seção cobre as campanhas e os templates que elas usam.

Como funciona

Rascunho→Enviando→Concluída

Uma campanha pode ainda ser Cancelada enquanto não termina.

`status`	Significado
`R`	Rascunho: criada, ainda não enviada.
`P`	Enviando (ou na fila de envio).
`A`	Concluída: todos os destinatários chegaram a um estado final.
`D`	Cancelada.

Ter um template aprovado
Crie em Templates gerenciados (ou na Meta) e espere o status A. Sincronize para atualizar.
Pré-visualizar o público
POST /broadcasts/preview mostra quantos casam e quantos receberão.
Criar a campanha
POST /broadcasts grava o rascunho com os destinatários já resolvidos.
Enviar e acompanhar
POST /broadcasts/{id}/send, depois GET /broadcasts/{id} para ver os contadores subirem.

Conceitos-chave

Template e janela de 24 horas

O WhatsApp só permite texto livre até 24 horas após a última mensagem do cliente. Campanhas, por definição, falam com quem não escreveu agora, então usam templates.

Categorias e custo

UTILITY (avisos de pedido), MARKETING (promoções, mais caro) e AUTHENTICATION (códigos). A Meta pode reclassificar um template; a categoria final fica no registro.

Público

Cinco formas de escolher: todos os clientes ativos com telefone, um grupo de usuários, uma lista de ids de clientes, uma lista de telefones ou filtros (grupo por nome, comprou nos últimos N dias, mínimo de pedidos).

Consentimento e descadastro

Duas barreiras. PARAR (descadastro) vale sempre. O consentimento de marketing (whatsapp_opt_in) só é exigido se a loja ativou essa regra. Os dois cortes entram em skipped_count. A regra de consentimento é reaplicada no momento do envio.

Variáveis do template

As variáveis são numeradas e, na campanha, iguais para todos: {"1":"30%","2":"30/11"}.

Endpoints

Método	Caminho	Para que serve	Página
`POST`	`/api/v1/admin/whatsapp/broadcasts/preview`	Conta quantas pessoas o público alcança e quantas receberão	Criar campanha
`POST`	`/api/v1/admin/whatsapp/broadcasts`	Cria uma campanha como rascunho, ou já a coloca em envio	Criar campanha
`GET`	`/api/v1/admin/whatsapp/broadcasts`	Lista as campanhas, as mais novas primeiro	Gerenciar campanhas
`GET`	`/api/v1/admin/whatsapp/broadcasts/{id}`	Devolve a campanha com a contagem de destinatários por situação	Gerenciar campanhas
`POST`	`/api/v1/admin/whatsapp/broadcasts/{id}/send`	Coloca a campanha em envio	Gerenciar campanhas
`POST`	`/api/v1/admin/whatsapp/broadcasts/{id}/cancel`	Cancela uma campanha que ainda não terminou	Gerenciar campanhas
`GET`	`/api/v1/admin/whatsapp/templates`	Lista os templates da conta WhatsApp Business da loja	Templates da Meta
`GET`	`/api/v1/admin/whatsapp/templates/models`	Lista modelos prontos de template e as variáveis disponíveis	Templates da Meta
`GET`	`/api/v1/admin/whatsapp/templates/managed`	Lista os templates gerenciados	Templates gerenciados
`POST`	`/api/v1/admin/whatsapp/templates/managed`	Cria um template na Meta e o registra na loja	Templates gerenciados
`PUT`	`/api/v1/admin/whatsapp/templates/managed/{id}`	Altera as configurações de um template gerenciado	Templates gerenciados
`DELETE`	`/api/v1/admin/whatsapp/templates/managed/{id}`	Exclui o template na Meta e na loja	Templates gerenciados
`POST`	`/api/v1/admin/whatsapp/templates/managed/sync`	Atualiza status e estrutura dos templates a partir da Meta	Templates gerenciados

Erros comuns

Filtrar a lista por status=draft: o filtro compara a letra (R). O resultado vem vazio sem erro.
Usar um template ainda pendente: a Meta recusa as mensagens. Espere A e sincronize.
Combinar send_immediately com scheduled_at: 400. E lembrar que scheduled_at só tem efeito depois do envio.
Esperar personalização por destinatário: as variáveis são fixas para todos.
Testar com all_customers: use phone_list com o seu número primeiro.
Ler a entrega em recipient_counts: use delivered_count e read_count da campanha.

Próximos passos

Criar campanha

Público, template e envio.

Templates gerenciados

Criar e acompanhar aprovação.

Mensagens enviadas

Histórico e reenvio.

API atual/Referência completa