WhatsApp API Oficial (Meta): integração completa

A integração com a API Oficial do WhatsApp Business da Meta é o caminho profissional pra disparar mensagens em escala — sem risco de banimento, com templates aprovados, e estabilidade garantida.

Esta página é o hub da feature: explica o que existe na seção /meta-api do app Rishi e aponta pros artigos detalhados de cada parte do fluxo.

O que está na seção /meta-api

A seção tem 5 telas principais, organizadas em volta da conexão (sua WABA — WhatsApp Business Account):

Conectando uma WABA: Embedded Signup

A criação de conexão usa o Embedded Signup da Meta — o fluxo OAuth que captura account_id, phone_number_id e o token de acesso sem você precisar entrar no Business Manager manualmente.

Passo resumido:

1. Em /meta-api, clique em Adicionar conexão.
2. Você é redirecionado pro fluxo da Meta.
3. Faz login no Facebook, escolhe ou cria a Business Account, escolhe ou cria o número.
4. Confirma as permissões.
5. A conexão volta pro Rishi já configurada e pronta pra usar.

Detalhes completos do Embedded Signup: o artigo Conectando sua conta WhatsApp Business no Rishi cobre passo a passo.

Por que API Oficial em vez de QR Code

Comparação aprofundada em Por que usar a API Oficial do WhatsApp Business.

Templates: o coração da API Oficial

Diferente do QR Code (mensagem livre), na API Oficial toda mensagem outbound usa um template aprovado pela Meta.

Sincronização

Templates são criados/aprovados pela Meta e o Rishi sincroniza pra você. Na tela /meta-api/{id}/templates:

• Importar templates busca todos os templates da sua WABA via Graph API e atualiza a base local
• Templates removidos da Meta são soft-deletados localmente (não excluídos pra preservar histórico)
• A coluna mensagens ativas mostra quantas mensagens do Rishi usam aquele template

Criação dentro do Rishi

Você também pode criar templates novos direto no Rishi (sem entrar no Business Manager):

1. Em /meta-api/{id}/templates, clique em Criar template.
2. Use um dos 6 modelos prontos (Boas-vindas, Acompanhe pedido, Oferta especial, etc.) ou comece do zero.
3. Defina header (texto, imagem ou vídeo), body, footer, botões (até 3).
4. Submeta. O template fica como PENDING até a Meta aprovar (geralmente alguns minutos).

Boas práticas e estrutura: Como criar templates que convertem (e custam menos).

Apenas templates NAMED

O Rishi suporta exclusivamente templates com parameter_format = NAMED (placeholders nomeados como {{nome_cliente}}). Templates antigos com {{1}}, {{2}} (posicionais) são marcados como inválidos e não podem ser usados em mensagens.

Por quê e como funciona: Como funcionam variáveis em templates.

Categorias

Templates são classificados pela Meta em três categorias:

A categoria afeta o custo Meta por conversa.

Mensagens: dois tipos

A seção tem duas telas separadas pra mensagens, com propósitos distintos:

1. Mensagens (webhook genérico)

/meta-api/{id}/messages

Mensagem que qualquer sistema externo pode disparar via POST numa URL assinada exclusiva. Útil pra:

• ERP enviando confirmação fora do WooCommerce
• n8n / Zapier orquestrando lógicas customizadas
• Código próprio integrado via API
• Aplicativos mobile que precisam mandar WhatsApp

Você cria a mensagem, configura o template + mapeamento de variáveis, e o Rishi te dá uma URL assinada. Quando alguém faz POST nessa URL com os campos esperados, a mensagem é disparada.

Setup e formato do payload: Recebendo eventos de outros sistemas via webhook.

2. WooCommerce

/meta-api/{id}/woocommerce

Mensagem atrelada a um evento específico do WooCommerce (pedido novo, status alterado, código de rastreio adicionado, etc.). Requer:

• O plugin WordPress instalado e conectado
• A conexão exibe is_wordpress_connected = true

A sincronização entre o Rishi e o plugin é bidirecional: ao criar/editar/excluir a mensagem no Rishi, o plugin é atualizado. Mensagens já configuradas no plugin antes da conexão são importadas automaticamente.

Hooks WooCommerce disponíveis

A lista é extensa: novo pedido, qualquer transição de status, status específicos (pendente, processando, concluído, cancelado, reembolsado, malsucedido), código de rastreio (Correios, Mandaê, Melhor Envio, JadLog, Infixs, WC Shipment Tracking, e qualquer transportadora), recuperação de senha, produto baixo estoque, produto sem estoque, nota pública adicionada.

Você ainda pode filtrar por gateway de pagamento, status de origem/destino, adicionar delay em segundos e restringir por categorias de produto (permitidas/bloqueadas).

Setup detalhado: Criando mensagens automáticas em eventos do WooCommerce. Plugin no WordPress: Instalando o plugin Automações para WhatsApp no WooCommerce.

Nova tentativa automática

Se a Meta recusar uma mensagem do WooCommerce por um motivo temporário, como limite de envios ou instabilidade, ela é enviada de novo uma única vez, 15 minutos depois. A recusa original continua registrada e o reenvio aparece como um registro novo. Enquanto a nova tentativa não acontece, o log mostra Nova tentativa às HH:MM.

Erros que não passam com o tempo, como o de um cliente que pediu para não receber marketing ou um template com problema, não são reenviados. As mensagens do webhook genérico não têm nova tentativa. Detalhes em Principais erros da API Oficial do WhatsApp (Meta).

Variáveis de templates

Templates usam placeholders nomeados que você mapeia pra variáveis do sistema na hora de criar a mensagem. As variáveis são organizadas em 8 grupos disponíveis no menu do mapeador:

• Pedido WooCommerce — 30+ variáveis (first_name, order_number, pix_code, tracking_code, etc.)
• Soluções administrativas — relatórios semanais
• Checkout inteligente
• Recuperação de senha
• Correios Updater
• Alertas de estoque
• CartFlows — carrinho abandonado
• Transportadoras genérico

Detalhes de cada grupo:

• Variáveis de pedido
• Variáveis de cliente
• Variáveis de cupom
• Variáveis de carrinho abandonado
• Quais variáveis usar em cada tipo de gatilho
• Variáveis dinâmicas em mensagens via webhook

Relatórios e saúde da conexão

/meta-api/{id}/report

A tela de relatórios mostra os números dos últimos 7 dias:

A tela responde diretamente perguntas como:

• "Meus envios estão funcionando?"
• "Qual template está falhando?"
• "Em qual horário minha loja mais dispara?"
• "Por que essa mensagem não chegou?"

Casos de borda comuns

Reprocessar logs com falha

Cada disparo gera um log de webhook com os dados recebidos, validações, resultado da Meta e IDs do Chat (se houver).

Logs com falha podem ser reenviados pelo botão Reprocessar na tela de edição da mensagem. O sistema cria um novo log com is_retry = true e despacha o job de processamento.

Enquanto uma nova tentativa automática estiver agendada, o Reprocessar fica indisponível no log original e no da nova tentativa, para o cliente não receber a mensagem duas vezes.

Integração com WordPress

Os campos wordpress_site_url e wordpress_sync_token da conexão são preenchidos quando o plugin WordPress é instalado e o setup é executado em /meta-api/{id}/woocommerce/setup. Esse endpoint gera um token Sanctum com escopo limitado (wordpress:register) que o plugin usa pra sincronizar mensagens e categorias.

is_wordpress_connected é true quando ambos os campos estão preenchidos. Sem isso, a aba WooCommerce mostra um aviso e bloqueia operações.

Setup do plugin no WP: Instalando o plugin Automações para WhatsApp.

Mapa de artigos relacionados

Pra entender a feature toda, percorra nesta ordem:

1. Por que usar a API Oficial do WhatsApp Business
2. Conectando sua conta WhatsApp Business no Rishi
3. Como criar templates que convertem (e custam menos)
4. Como funcionam variáveis em templates
5. Quais variáveis usar em cada tipo de gatilho
6. WooCommerce: Instalando o plugin → Criando mensagens automáticas em eventos do WooCommerce
7. Webhook genérico: Recebendo eventos de outros sistemas → Variáveis em mensagens via webhook
8. Variáveis em detalhe: Pedido, Cliente, Cupom, Carrinho abandonado

Próximos passos

• Conexões e setup do Embedded Signup.
• WhatsApp via QR Code — alternativa rápida sem aprovação Meta.
• Visão geral do Flow Builder — use a API Oficial em automações dentro do Rishi CRM.