BK-295 - WhatsApp Marketing Messages API oficial

Status: aberto

Responsavel: Codex

Aberto em: 2026-04-30 23:48 -03

Contexto

O RioNoTeatro quer voltar o envio real de WhatsApp para a API oficial da Meta e avaliar a API de Mensagens de Marketing para WhatsApp, anteriormente chamada de Marketing Messages Lite API / MM Lite.

A decisao operacional correta para o RioNoTeatro e usar a trilha Aumente o ROI com mensagens de marketing com otimizacoes. A trilha Torne-se um Provedor de Tecnologia e para empresas que vao operar WhatsApp/API para clientes de terceiros, com onboarding de WABAs de outros negocios.

Aprendizados desta sessao

• A pagina de visao geral da Meta foi atualizada em 2026-02-10 e afirma que a API de Mensagens de Marketing para WhatsApp esta disponivel para todos.
• A API de MM para WhatsApp e descrita pela Meta como solucao de marketing de ultima geracao para melhorar a experiencia do cliente e entregar a mensagem certa para mais pessoas.
• Principais beneficios oficiais:
• otimizacoes automaticas de entrega para alcançar mais pessoas propensas a considerar a mensagem importante;
• mais leituras e cliques;
• insights exclusivos de mensuracao, incluindo referencias de desempenho contra empresas semelhantes;
• recomendacoes personalizadas para melhorar campanha;
• otimizacoes automaticas de criativos em teste, como animacao de imagens e filtros;
• formatos de midia avancados, incluindo GIFs;
• tempo de vida / TTL para evitar entrega atrasada ou irrelevante em campanhas urgentes;
• esquema tecnico semelhante ao da Cloud API;
• mesmo modelo de cobranca da Cloud API;
• reaproveitamento de numeros de telefone e modelos de mensagem de marketing existentes.
• A orientacao oficial e enviar todo trafego de marketing para /{PHONE_NUMBER_ID}/marketing_messages, permitindo roteamento automatico para empresas qualificadas.
• A nota de rodape do ganho de ate 9% vem de teste A/B com cerca de 12 milhoes de mensagens de marketing entregues, na India, entre 2025-01-01 e 2025-01-31, comparando entrega otimizada da MM API com entrega padrao da Cloud API entre mensagens de alto engajamento, com teste t a 95% de confianca.
• Interpretacao operacional: disponivel para todos nao dispensa validar token, WABA, numero, termos/status de onboarding e estado do numero antes de envio real.
• Templates de marketing personalizados devem ser criados via API de Modelos de Mensagens:
• endpoint: POST /{WHATSAPP_BUSINESS_ACCOUNT_ID}/message_templates;
• category: marketing;
• language: idioma do template, ex. pt_BR;
• parameter_format: formato dos parametros, preferencialmente nomeado quando usamos placeholders controlados;
• components podem incluir header com imagem, body com parametros nomeados e exemplos, footer e buttons;
• botoes suportados no exemplo: url, phone_number e quick_reply;
• para cabecalho de imagem, a criacao exige HEADER_ASSET_HANDLE, ou seja, upload/handle de midia antes da submissao;
• o template precisa ser aprovado pela Meta antes de envio real.
• Modelos de oferta por tempo limitado sao candidatos fortes para o RioNoTeatro porque campanhas de pecas/ofertas saem de cartaz e tem urgencia real.
• Doc Meta atualizada em 2025-11-04.
• Permitem exibir validade e contagem regressiva para codigos de oferta em modelos de mensagem.
• Somente templates MARKETING sao compativeis.
• Componentes de rodape nao sao compativeis.
• WhatsApp Web/Desktop nao exibem a oferta; o usuario ve aviso de mensagem nao compativel com o cliente usado.
• Endpoint de criacao continua POST /{WHATSAPP_BUSINESS_ACCOUNT_ID}/message_templates.
• Componentes do exemplo: header, limited_time_offer, body e buttons.
• limited_time_offer inclui text e has_expiration.
• Botoes do exemplo: copy_code para codigo de oferta e url para pagina de compra.
• Para RNT, avaliar usar copy_code para cupom/oferta e botao URL com shortlink rastreavel do espetaculo/campanha.
• O quickstart AdsSample da Meta, com facebook-nodejs-business-sdk, AdAccount, Campaign, ads_management e conta act_*, e da Marketing/Ads API. Ele nao configura WhatsApp, nao habilita MM API e nao deve ser executado na VPS para esta frente.
• Tokens colados no chat devem ser tratados como segredo comprometido operacionalmente. Nao registrar token bruto em docs, Git, logs ou comandos. O caminho correto e provisionar token direto no .env/cofre e validar sempre com saida mascarada.
• O token para WhatsApp precisa ter permissoes de WhatsApp, principalmente whatsapp_business_messaging e whatsapp_business_management. Para algumas consultas de status/ativos, pode ser necessario business_management.
• A implementacao atual BK-292/BK-293 usa Cloud API padrao no endpoint /{PHONE_NUMBER_ID}/messages.
• A Marketing Messages API usa endpoint especifico: POST /{WHATSAPP_BUSINESS_PHONE_NUMBER_ID}/marketing_messages.
• O numero comercial tambem precisa estar registrado na Cloud API; numeros nao registrados na Cloud API nao podem usar a Marketing Messages API.
• Evidencia tecnica de 2026-05-24 17:18 -03:
• .env tem BOT_WHATSAPP_OFFICIAL_PHONE_NUMBER_ID, BOT_WHATSAPP_OFFICIAL_WABA_ID e BOT_WHATSAPP_OFFICIAL_ACCESS_TOKEN configurados, sem expor segredo bruto.
• test-send oficial com template hello_world e idioma en_US para allowlist admin 5521999605790 foi executado pelo CLI seguro.
• Meta respondeu HTTP 400 com (#133010) Account not registered; evento local whatsapp_campaign_events.id=1035, event_type=admin_test_failed.
• Consulta mascarada do PHONE_NUMBER_ID retornou display_phone_number=+55 21 99960-5790, verified_name=Rio no Teatro Entretenimento, quality_rating=UNKNOWN, code_verification_status=NOT_VERIFIED, name_status=AVAILABLE_WITHOUT_REVIEW e platform_type=ON_PREMISE.
• Interpretacao operacional: payload, token e rota chegam ate a Meta, mas o numero real ainda nao esta registrado/verificado na Cloud API. Manter envio oficial/MM bloqueado ate concluir registro/migracao ou usar um PHONE_NUMBER_ID de numero Cloud/test number valido.
• Evidencia tecnica de 2026-05-24 17:36 -03:
• Admin informou novo token permanente gerado para o app App RNT cloud api, identificacao 61590051255278, com acesso Employee.
• IDs canonicos para chamadas de API: WABA_ID=184255154767640 e PHONE_NUMBER_ID=192394897284461.
• .env foi atualizado sem expor segredo bruto: BOT_WHATSAPP_PROVIDER=official e BOT_WHATSAPP_OFFICIAL_ACCESS_TOKEN renovado.
• Leitura local mascarada confirmou provider official, PHONE_NUMBER_ID, WABA_ID e token definidos.
• Consulta Graph API ao PHONE_NUMBER_ID respondeu HTTP 200, com display_phone_number=+55 21 99960-5790, verified_name=Rio no Teatro Entretenimento, quality_rating=UNKNOWN, platform_type=ON_PREMISE e code_verification_status=NOT_VERIFIED.
• Teste tecnico isolado de envio oficial para allowlist admin 5521999915554 respondeu HTTP 400 com (#133010) Account not registered.
• Interpretacao operacional: o novo token tem acesso suficiente para consultar o ativo, mas o numero real segue sem registro Cloud API. A proxima acao nao e gerar outro token; e registrar/migrar/verificar o numero no WhatsApp Cloud API ate deixar de aparecer como ON_PREMISE/NOT_VERIFIED.
• Antes de enviar pela MM API, validar a WABA:
• GET /{WABA_ID}?fields=marketing_messages_onboarding_status
• ELIGIBLE indica WABA qualificada.
• ONBOARDED indica WABA integrada.
• Em respostas/fluxos relacionados tambem aparecem TERM_OF_SERVICE_SIGNED, REQUEST_SENT e NOT_STARTED.
• O campo antigo marketing_messages_lite_api_status aparece como alternativa, mas esta obsoleto; usar marketing_messages_onboarding_status.
• Para parceiro/listagem de WABAs qualificadas compartilhadas:
• GET /{BUSINESS_ID}/client_whatsapp_business_accounts?filtering=[{'field':'marketing_messages_onboarding_status','operator':'IN','value':['ELIGIBLE']}]
• O aceite dos Termos de Servico da API de MM para WhatsApp pode ser feito no App Dashboard > WhatsApp > Inicio rapido, no card de Marketing Messages, ou pelo WhatsApp Manager quando aplicavel.
• A doc oficial tambem menciona compartilhamento de atividade de evento para otimizar campanhas. Por mensagem, o parametro message_activity_sharing pode ser usado no payload da MM API para sobrescrever a configuracao padrao da WABA.

Decisoes

• Nao seguir a trilha de Provedor de Tecnologia agora.
• Nao rodar sample de Ads API na VPS.
• Implementar a MM API como rota oficial separada, sem substituir cegamente o provider official existente.
• Manter fallback/guardrail: se WABA nao estiver elegivel/onboarded ou se o token nao tiver permissoes corretas, bloquear envio pela MM API e nao cair em envio real silencioso.
• Continuar com dry-run/allowlist/confirmacao textual antes de qualquer envio real.

Dados que ainda faltam validar/provisionar

• Numero oficial registrado/verificado na Cloud API; em 2026-05-24, o PHONE_NUMBER_ID configurado respondeu platform_type=ON_PREMISE e code_verification_status=NOT_VERIFIED.
• Confirmar se o token atual tem permissoes de WhatsApp suficientes alem de chegar ao endpoint de phone number e mensagens.
• Status real de marketing_messages_onboarding_status.
• Template marketing aprovado para PT-BR, ou estrategia temporaria usando template aprovado existente.
• Verify token/webhook oficial ja existe como conceito, mas precisa permanecer no .env e ser validado sem expor segredo.

Evidencias humanas recebidas

• WhatsApp Manager > Telefones mostra o numero comercial +55 21 99960-5790.
• Nome exibido: Rio no Teatro Entretenimento.
• Pais: Brasil.
• Estado informado na tela: Offline.
• Classificacao de qualidade informada na tela: Indisponivel.
• Interpretacao operacional: antes de envio real, confirmar se o numero esta registrado/ativo na Cloud API e obter o PHONE_NUMBER_ID; enquanto a tela indicar offline/qualidade indisponivel, tratar envio oficial/MM API como nao liberado para producao.
• Historico no WhatsApp Manager:
• 2026-04-30 12:00 -03, usuario Deleted User, categoria Perfil comercial, atividade Perfil comercial atualizado para +55 (21) 99960-5790.
• Interpretacao operacional: esse evento indica alteracao recente no perfil comercial por usuario hoje inexistente/removido; considerar em auditoria de acesso/configuracao antes de producao.

Plano tecnico futuro

1. Provisionar variaveis oficiais no .env, com backup pre-edicao.
2. Criar comando de diagnostico mascarado para validar token, permissoes, WABA, phone number id e status de onboarding.
3. Estender config/bot_config.php com constantes da MM API:

• BOT_WHATSAPP_OFFICIAL_WABA_ID
• BOT_WHATSAPP_OFFICIAL_MARKETING_PROVIDER ou flag equivalente
• default seguro para message_activity_sharing

1. Estender includes/whatsapp_helper.php com sender separado para /{PHONE_NUMBER_ID}/marketing_messages.
2. Estender CLI admin/cron/whatsapp_campaign_queue.php para teste controlado:

• dry-run por padrao;
• --provider=official-mm ou nome equivalente;
• --execute --confirm=SEND_ADMIN_TEST apenas em allowlist.

1. Persistir provider usado e resposta da Meta em whatsapp_campaign_events.
2. Garantir que cloud_webhook.php continue processando status, inbound e opt-out, incluindo eventos da rota MM quando chegarem.
3. Documentar resultado dos smokes reais sem expor tokens.

Criterios de aceite

• php -l nos arquivos alterados.
• Diagnostico mascarado mostra token com permissoes WhatsApp, WABA ID, Phone Number ID e status de onboarding.
• WABA ELIGIBLE ou ONBOARDED antes de qualquer envio pela MM API.
• Envio de teste real apenas para allowlist admin e com confirmacao textual.
• Logs e eventos nao armazenam token bruto.
• Se a Meta retornar erro de permissao/onboarding, o sistema falha fechado e mantem a fila sem disparo real.