WhatsApp Broadcast

Dispara mensagens segmentadas pela API oficial do WhatsApp.

Este plugin do Claude Code conecta seus fluxos de trabalho à WhatsApp Cloud API da Meta para enviar campanhas de mensagens para segmentos de contatos usando templates de mensagem aprovados. Ele foi desenhado para ser usado de forma responsável: respeita a janela de atendimento de 24 horas, exige opt-in explícito dos contatos e nunca envia conteúdo fora das regras da Meta.

O que faz

O whatsapp-broadcast transforma o Claude Code em um operador de campanhas de WhatsApp dentro do terminal. Com ele você pode:

• Montar e revisar uma campanha de broadcast para um segmento de contatos.
• Enviar templates aprovados (categoria de marketing, utilidade ou autenticação) em lote, com variáveis personalizadas por contato.
• Validar o opt-in e a conformidade antes de qualquer disparo (pré-visualização sem enviar nada).
• Consultar o status de entrega (enviado, entregue, lido, falhou) de uma campanha já disparada.
• Gerenciar a janela de 24 horas de atendimento ao cliente, escolhendo automaticamente entre mensagem livre (dentro da janela) e template (fora da janela).

Tudo passa pela API oficial. Não há automação não autorizada, scraping de contatos nem uso de números não verificados.

Instalação

1. Tenha uma conta da Meta Business com um número de telefone verificado na WhatsApp Cloud API.
2. Crie e aprove pelo menos um template de mensagem no Gerenciador do WhatsApp (campanhas de marketing exigem templates aprovados).
3. Copie a pasta deste plugin para o diretório de plugins do seu projeto Claude Code.
4. Defina as variáveis de ambiente descritas em Configuração.
5. Reinicie a sessão do Claude Code para que os comandos do plugin sejam carregados.

Comandos disponíveis

• /enviar-broadcast — Monta e dispara uma campanha de broadcast com um template aprovado para um segmento de contatos, validando opt-in e a janela de 24h antes do envio.
• /status-entrega — Consulta o status de entrega (enviado, entregue, lido, falhou) de uma campanha ou de mensagens específicas e resume os resultados.

Configuração

O plugin lê as credenciais exclusivamente de variáveis de ambiente. Nunca coloque os valores reais em arquivos versionados — use apenas os nomes abaixo no seu .env local ou no gerenciador de segredos.

| Variável de ambiente | Para que serve |

| --- | --- |

| WHATSAPP_ACCESS_TOKEN | Token de acesso da Meta usado para autenticar as chamadas à Graph API. |

| WHATSAPP_PHONE_NUMBER_ID | ID do número de telefone remetente registrado na Cloud API. |

| WHATSAPP_BUSINESS_ACCOUNT_ID | ID da conta WhatsApp Business (WABA), usado para listar e validar templates. |

Boas práticas:

• Gere tokens de longa duração ou de sistema para evitar expiração no meio de campanhas.
• Restrinja as permissões do token ao mínimo necessário (whatsapp_business_messaging, whatsapp_business_management).
• Rotacione o WHATSAPP_ACCESS_TOKEN periodicamente e revogue-o caso suspeite de vazamento.

Exemplo de uso

Pré-visualizar e disparar uma campanha de boas-vindas para o segmento de novos alunos:

/enviar-broadcast template=boas_vindas segmento=novos-alunos idioma=pt_BR variaveis=nome,curso preview

O Claude vai:

1. Carregar o segmento novos-alunos (de um CSV/JSON do seu projeto).
2. Verificar que todos os contatos têm opt-in registrado.
3. Mapear as variáveis nome e curso para cada contato.
4. Mostrar uma pré-visualização da mensagem renderizada sem enviar nada (modo preview).

Depois de revisar, basta remover preview para disparar de verdade. Em seguida:

/status-entrega campanha=boas_vindas-2026-06-16

retorna um resumo: quantas foram entregues, lidas, ou falharam, com os motivos das falhas.

Segurança e limites

• Opt-in obrigatório: só envie para contatos que autorizaram explicitamente o recebimento. O plugin bloqueia o disparo se o opt-in não estiver registrado para um contato.
• Janela de 24 horas: fora da janela de atendimento (24h após a última mensagem do cliente) só é permitido enviar templates aprovados. Mensagens de formato livre só dentro da janela.
• Templates aprovados: campanhas de marketing exigem templates previamente aprovados pela Meta. O plugin valida o status do template antes de enviar.
• Limites de taxa e qualidade: a Meta aplica limites de mensagens (tiers) e uma classificação de qualidade do número. Disparos excessivos ou marcados como spam podem rebaixar o número. Respeite os limites e segmente bem.
• Segredos: as credenciais ficam apenas em variáveis de ambiente, nunca em logs ou no histórico. Não exponha o WHATSAPP_ACCESS_TOKEN em saídas de comando.
• Conformidade: respeite a LGPD e as políticas comerciais do WhatsApp. Inclua sempre uma forma de cancelar o recebimento (opt-out).