📘 Documentação — API Oficial WhatsApp
Bem-vindo à documentação de implantação da API Oficial do WhatsApp Business. Aqui você encontra apenas o fluxo Meta — requisitos, conexão por Coexistência e operação.
Conexão apenas via Coexistência (Coex)
O Chat Jurídico conecta seu número à API Oficial somente pelo fluxo de Coexistência. Assim você usa o WhatsApp Business App e a API Oficial no mesmo número: ideal para preservar histórico e atender via app + automação.
- Enviar campanhas para 250+ contatos via API
- Manter conversas 1:1 pelo App de Negócios
- Sincronizar conversas em toda a plataforma
- Preservar histórico — sem perda de dados
- Manter conversas em grupo intactas
Etapas do Processo (Meta)
📋 Etapa 1
Requisitos Meta — BM, 2FA, Verificação, Facebook, Website
📱 Etapa 2
WhatsApp e WABA — App, Número, Desconexão
🔗 Etapa 3
Conexão Meta — Coexistência (QR)
📝 Etapa 4
Templates — Criar, Submeter, Aprovação
🚀 Etapa 5
Operação — Pós-conexão, Pagamento, Entrega
🔧 Troubleshooting
Resolução de problemas comuns
Business Manager (BM)
O Meta Business Manager (Portfólio de Negócios) é obrigatório para usar a API Oficial do WhatsApp. É o ponto de partida de toda implantação.
Verificações
- BM existe e está ativo? — Se não, criar em
business.facebook.com - Cliente é administrador? — Precisa de Controle Total, não apenas Acesso Parcial
- Conta com 72h+? — Contas recém-criadas precisam de período de maturação
Sem Business Manager configurado, não é possível conectar a API Oficial.
Como Criar um BM
- Acessar business.facebook.com
- Clicar em "Criar conta"
- Preencher dados da empresa (nome exato do CNPJ)
- Confirmar email
Tempo estimado: 15 min + 72h de espera
Verificação da Empresa
Nem sempre a Meta exige verificação. Antes de iniciar, verifique o status atual no BM.
Status Possíveis
- Verificada — pode prosseguir normalmente
- Em análise — aguardar 24-72h após envio de documentos
- Não verificada (sem exigência) — pode prosseguir
- Não verificada (Meta exige) — enviar documentos
Documentos Necessários
- Razão Social exata (conforme CNPJ)
- Endereço comercial completo
- Telefone comercial
- Documento do responsável (CNH ou Passaporte)
Dica: use a ferramenta de redimensionar imagem para ajustar fotos de documentos (1500×1000 pixels).
Tempo: 10 min (preparar) + 24-72h (análise Meta)
Autenticação em Dois Fatores (2FA)
A Meta exige 2FA para todos os administradores do BM. Sem 2FA ativo, a autorização da API será bloqueada.
Como Ativar
- Baixar o
Google Authenticator (se ainda não tiver) - Acessar o Centro de Contas
- Ir em Segurança e login
- Ativar Autenticação de dois fatores
- Escolher método: App ( Google Authenticator)
Tempo estimado: 5-10 min
Página Facebook
Obrigatório ter uma Página Facebook vinculada ao Business Manager.
Verificações
- Página existe e está ativa
- Página está vinculada ao BM correto
- Se não existe: criar em facebook.com/pages/create
Tempo estimado: 5-10 min
Website Compliance
O website da empresa deve atender aos requisitos da Meta para passar na verificação.
Itens Obrigatórios
- Termos de Uso publicados e acessíveis
- Política de Privacidade publicada e acessível
- CNPJ visível no rodapé ou página "Sobre"
Website sem esses itens pode ter verificação rejeitada pela Meta.
Se o cliente ainda não tem site, o Escritori.ai cria um "linktree" profissional do escritório em poucos minutos.
WhatsApp Business App
O cliente precisa ter o WhatsApp Business (não o WhatsApp normal) instalado e ativo no celular.
Verificações
- App WhatsApp Business instalado (não WhatsApp normal)
- Número ativo e configurado
- Perfil comercial preenchido
Se o cliente usa WhatsApp normal, precisa migrar para o Business primeiro. Fazer backup antes!
Status do Número
Verificar se o número está livre para conectar à API Oficial.
Cenários
- Livre — pode conectar diretamente
- Conectado a outra API (Z-API, Evolution, etc.) — precisa desconectar primeiro
- Apenas WhatsApp Web — OK, não interfere
Desconectar API Atual
Se o número está conectado a outra API (Z-API, Evolution, etc.), precisa desconectar primeiro.
Passo a Passo
- Abrir WhatsApp Business no celular
- Ir em Configurações → Conta
- Acessar Plataforma comercial
- Tocar em "Desconectar"
Aguardar pelo menos 24 horas após desconectar antes de tentar reconectar.
🔀 Tipo de Conexão
Existem dois métodos para conectar o número à API Oficial:
| Padrão (PIN) | Coexistência (QR) | |
|---|---|---|
| Método | Código PIN de 6 dígitos | QR Code no celular |
| App no celular | Perde acesso ao app | App continua funcionando |
| Histórico | Não preserva | Importa até 6 meses |
| Contatos | Não importa | Importa todos |
| Selo azul | Pode perder | Preserva |
| Ideal para | Quem vai usar só API | PMEs que querem app + API |
Perguntar ao cliente: "Você quer continuar usando o WhatsApp Business App no celular?" Se sim → Coexistência.
Conexão Padrão (PIN)
O fluxo padrão migra o número inteiramente para a API. O WhatsApp Business App perde o acesso.
Passo a Passo
- Verificar que o cliente está logado no Facebook com a conta do BM
- Iniciar conexão na plataforma Chat Jurídico
- Popup de autorização Meta abre
- Selecionar o BM correto
- Selecionar ou criar WABA
- Selecionar o número
- Código PIN de 6 dígitos aparece no celular: Configurações → Conta → Plataforma comercial
- Inserir o PIN na tela
- Conexão estabelecida!
🔄 Coexistência WhatsApp — Guia Completo
O que é Coexistência (Coex)?
A Coexistência do WhatsApp é uma solução da Meta que permite usar tanto o Aplicativo de Negócios do WhatsApp quanto a API do WhatsApp Cloud ao mesmo tempo com o mesmo número de telefone. Isso significa que você pode continuar usando o Aplicativo de Negócios para conversas 1:1 enquanto amplia a comunicação por meio das ferramentas de automação.
Para quem é a Coex?
Pequenas e médias empresas que desejam preservar o histórico de conversas anteriores enquanto atualizam para uma plataforma mais poderosa para campanhas.
Também é ideal para equipes de vendas que usam a Caixa de Entrada da Equipe e empresas que oferecem produtos/serviços de alto valor ou vendas consultivas.
O que você pode fazer com a Coex?
- Enviar campanhas para 250+ contatos via API de Nuvem
- Iniciar conversas 1:1 diretamente do Aplicativo de Negócios do WhatsApp
- Sincronizar todas as conversas em toda a plataforma, para que sua equipe fique informada
- Manter todo o histórico de mensagens — sem perda de dados ao mudar
- Manter as conversas em grupo intactas no aplicativo do WhatsApp
Por que a Coexistência é importante?
Anteriormente, mudar para a API de Nuvem significava perder o acesso ao Aplicativo de Negócios e ao histórico de conversas. A Coexistência remove essa limitação — permitindo que você automatize as mensagens enquanto retém o acesso às conversas anteriores e continua as conversas pessoais no App.
Pré-requisitos
- WhatsApp Business App instalado e ativo (versão 2.24.17 ou superior)
- Número ativo no app por pelo menos 7 dias (ideal: 30-60 dias)
- País suportado (Brasil ✅)
- Página de Negócios do Facebook com acesso de administrador
- Meta Business Manager configurado
- Número não conectado a outra API
Processo de Conexão (5 Etapas)
Etapa 1 — Escolher Método de Integração
Na tela inicial, escolher "Conectar seu aplicativo WhatsApp Business (Coexistência do WhatsApp)".
Etapa 2 — Iniciar Configuração
- Continuar com o Facebook — fazer login com conta de administrador do BM
- Conceder permissões solicitadas
- Selecionar Portfólio de Negócios — o nome preenche automaticamente
- Conectar WhatsApp Business existente — NÃO escolher "Conectar número de telefone"
- Adicionar número — inserir número ativo, confirmar nome e fuso horário
O nome da empresa NÃO pode ser alterado após a integração. Verifique antes de confirmar.
Etapa 3 — Vincular via QR Code
Um QR Code aparece na tela "Compartilhar Contatos e Chats":
- O cliente recebe uma mensagem do Facebook Business no app
- Abrir mensagem → Conectar
- Clicar em Conectar à Plataforma de Negócios
- Escanear o QR Code com a câmera
Etapa 4 — Importar Histórico
| Dado | Importação |
|---|---|
| Contatos | Todos — automático |
| Chats 1:1 | Até 6 meses |
| Mídias | Até 2 semanas |
| Chats em grupo | ❌ Não importados (ficam no app) |
A importação está ativada por padrão. Se pular e mudar de ideia, precisa desvincular e vincular novamente.
Etapa 5 — Confirmar Conexão
A conexão pode levar até 2 minutos. Após sucesso:
- Contatos importados automaticamente
- Chats sincronizados conforme seleção
- Confirmação em: Configurações > Conta > Conectar à Plataforma de Negócios
Pós-Conexão
Sincronização de Dados
| Dados | Sincronização | Momento |
|---|---|---|
| Todos os contatos | Segundo plano | Imediato |
| Chats (últimas 24h) | Tempo real | Imediato |
| Chats (últimos 90 dias) | Segundo plano | Inicia imediatamente |
| Chats (últimos 6 meses) | Segundo plano | Inicia imediatamente |
Configurações Obrigatórias
- Desativar automações do WhatsApp Business App (boas-vindas, ausência)
- Revincular dispositivos compatíveis (WhatsApp Web, Mac)
- Dispositivos NÃO compatíveis: WhatsApp Windows e WearOS
Preços após a integração com Coex
Uma vez que sua empresa esteja configurada na API de Nuvem:
- Mensagens pelo Aplicativo de Negócios do WhatsApp → Gratuitas
- Mensagens enviadas via API → seguem os preços da API de Nuvem da Meta
Selo Azul (Meta Verified)
Se o número já tem Meta Verified, o selo azul é mantido ao usar Coexistência. No Embedded Signup tradicional (removendo do app), o selo é perdido.
Suporte a Múltiplos Números
O recurso de Números Múltiplos permite conectar vários números de telefone a uma conta, gerenciando todos em um só lugar.
- Cada número pode ser integrado por Coexistência ou Inscrição Incorporada MM Lite
- Ex.: integrar um pela Coex e outro pela Inscrição Incorporada
- Todos os contatos e conversas aparecem nas guias Contatos e Caixa de Entrada da Equipe
- Contatos do App de Negócios são identificados pelo rótulo de Origem "Aplicativo de Negócios do WhatsApp"
- Conversas de números conectados via Coex são sincronizadas em tempo real
Como Desconectar a Coexistência
- Abrir WhatsApp Business App no celular
- Configurações → Conta → Plataforma de Negócios
- Tocar em Desconectar
NÃO desinstale o app — isso pode criar problemas na reintegração. A desconexão só pode ser feita pelo app.
Conclusão
O melhor de dois mundos
- Mensagens 1:1 sem interrupções do App de Negócios
- Automação escalável e campanhas via API
- Zero interrupção nas conversas existentes
Se você estava hesitante em mudar devido à perda de dados ou limitações de mensagens, a Coex muda tudo.
📋 Coex: Recursos e Limitações
Aqui está o que muda (e o que não muda) após habilitar a Coexistência, tanto no Aplicativo de Negócios do WhatsApp quanto na API de Nuvem.
| Recurso no App de Negócios | O que muda no App após Coex | Sincronizado para a API de Nuvem |
|---|---|---|
| Conversas 1:1 | Editar e revogar mensagens não são mais suportados | ✅ Sincronizado — últimos 6 meses. Sincronização bidirecional: futuras mensagens no App também aparecem na API e vice-versa |
| Contatos | Nenhuma mudança | ✅ Sincronizado — todos os dados de contato. Sincronização unidirecional: edições no App refletem na API |
| Conversas em grupo | Nenhuma mudança | ❌ Não sincronizado |
| Ocultação de número | Nenhuma mudança | ❌ Não sincronizado |
| Mensagens que desaparecem | ⚠️ Desativadas para todas as conversas 1:1 | ❌ Não sincronizado |
| Mensagens de visualização única | ⚠️ Desabilitadas para todas as conversas 1:1 | ❌ Não sincronizado |
| Localização ao vivo | ⚠️ Desabilitada para todas as conversas 1:1 | ❌ Não sincronizado |
| Listas de campanhas | ⚠️ Não pode criar novas. Existentes ficam somente leitura | ❌ Não sincronizado |
| Chamadas de voz e vídeo | Nenhuma mudança | ❌ Não sincronizado |
| Ferramentas de negócios (catálogo, pedidos, status) | Nenhuma mudança | ❌ Não sincronizado |
| Ferramentas de mensagens (marketing, boas-vindas, respostas rápidas, rótulos) | Nenhuma mudança | ❌ Não sincronizado |
| Perfil de negócios (nome, endereço, site) | Nenhuma mudança | ❌ Não sincronizado |
| Canais | Nenhuma mudança | ❌ Não sincronizado |
Preços após integração com Coex
Modelo de preços
- Mensagens pelo Aplicativo de Negócios do WhatsApp → continuam gratuitas
- Mensagens via API de Nuvem → seguem os preços da API de Nuvem da Meta
Suporte a Múltiplos Números
O recurso de Números Múltiplos permite conectar vários números de telefone a uma conta, gerenciando todos em um só lugar.
- Cada número pode ser integrado por Coexistência ou Inscrição Incorporada MM Lite
- Exemplo: integrar um pela Coex e outro pela Inscrição Incorporada
- Todos os contatos e conversas aparecem nas guias Contatos e Caixa de Entrada da Equipe
- Contatos do App de Negócios são identificados pelo rótulo "Aplicativo de Negócios do WhatsApp"
- Conversas de números conectados via Coex são sincronizadas em tempo real
❓ Coex: Perguntas Frequentes
Perguntas Gerais
A Coexistência do WhatsApp é uma solução da Meta que permite usar tanto o Aplicativo de Negócios do WhatsApp quanto a API do WhatsApp Cloud ao mesmo tempo com o mesmo número de telefone. Isso significa que você pode continuar usando o Aplicativo de Negócios para conversas 1:1 enquanto amplia a comunicação por meio das ferramentas de automação.
Anteriormente, mudar para a API de Nuvem significava perder o acesso ao Aplicativo de Negócios e ao histórico de conversas. A Coexistência remove essa limitação — permitindo que você automatize as mensagens enquanto retém o acesso às conversas anteriores e continua as conversas pessoais no Aplicativo de Negócios.
A Coexistência é ideal para:
- Equipes de vendas que usam a Caixa de Entrada da Equipe
- Empresas que oferecem produtos ou serviços de alto valor ou vendas consultivas
- Pequenas e médias empresas que desejam preservar o histórico de mensagens do WhatsApp enquanto atualizam para uma plataforma mais poderosa para campanhas
Recursos e Capacidades
Sim, você pode enviar campanhas de WhatsApp para mais de 250 contatos usando a API de Nuvem, enquanto ainda usa o Aplicativo de Negócios para conversas individuais.
Sim, até 6 meses de histórico de conversas podem ser sincronizados entre o Aplicativo de Negócios do WhatsApp e a plataforma. As futuras mensagens continuarão a ser sincronizadas nos dois sentidos.
Conversas individuais 1:1 e dados de contato são sincronizados. No entanto, conversas em grupo, mensagens que desaparecem, mensagens de visualização única e certos tipos especiais de mensagens não são sincronizados.
Alguns recursos não serão mais suportados em conversas 1:1 após habilitar a Coexistência:
- Mensagens que desaparecem
- Mídia de visualização única
- Compartilhamento de localização ao vivo
- Criação de novas listas de campanhas (existentes ficam somente leitura)
Sim, não há mudanças nas conversas em grupo ou chamadas de voz/vídeo dentro do Aplicativo de Negócios, mas elas não serão sincronizadas com a API.
Preços e Uso
Não. As mensagens enviadas pelo Aplicativo de Negócios do WhatsApp continuam gratuitas. No entanto, as mensagens enviadas via API seguem os preços da API de Nuvem da Meta.
Suporte a Múltiplos Números
Sim. Você pode integrar cada número usando o método de Coexistência ou o processo de Inscrição Incorporada MM Lite.
Todos os contatos e conversas aparecem nas guias Contatos e Caixa de Entrada da Equipe. As conversas de números conectados via Coexistência são sincronizadas em tempo real, para que sua equipe fique atualizada.
Os contatos do Aplicativo de Negócios do WhatsApp são rotulados com a tag de origem "Aplicativo de Negócios do WhatsApp", tornando-os fáceis de filtrar e gerenciar.
Criar Templates de Mensagem
Templates são modelos de mensagem pré-aprovados pela Meta, necessários para iniciar conversas proativas.
Tipos de Template
- Marketing — promoções, ofertas, novidades
- Utilidade — confirmações, notificações, lembretes
- Autenticação — códigos de verificação
Boas Práticas
- Usar linguagem clara e objetiva
- Incluir o nome da empresa
- Evitar linguagem promocional em templates de utilidade
- Usar variáveis para personalização (nome, número do pedido, etc.)
Aprovação de Templates
Todos os templates precisam ser aprovados pela Meta antes do uso.
Status Possíveis
- Aprovado — pronto para uso
- Pendente — aguardando análise (24-48h)
- Rejeitado — ajustar conforme feedback e reenviar
Motivos Comuns de Rejeição
- Linguagem promocional em template de utilidade
- Variáveis mal formatadas
- Conteúdo que viola políticas da Meta
Pós-Conexão
Após a conexão (seja Padrão ou Coexistência), configurações adicionais são necessárias.
Checklist Pós-Conexão
- Testar envio e recebimento de mensagens
- Cadastrar cartão internacional para cobranças da Meta
- Configurar templates de mensagem
- Configurar IA e automações no Chat Jurídico
- Treinar equipe no uso da plataforma
Se conexão via Coexistência
- Desativar automações do WhatsApp Business App
- Revincular dispositivos compatíveis (WhatsApp Web, Mac)
- Verificar sincronização de contatos e histórico
💳 Cartão Internacional
Obrigatório após conectar: cadastrar cartão internacional para cobranças da Meta. O cartão é vinculado à WABA criada durante a conexão.
Passo a Passo
- Acessar BM → Cobrança → WhatsApp Business
- Selecionar a conta WABA do número
- Adicionar cartão de crédito internacional
- Cartão deve aceitar cobranças em USD (dólares)
- Validar que o cartão foi aceito
ATENÇÃO: O pagamento da API é SEPARADO do pagamento de anúncios Facebook/Instagram. Cada número conectado precisa de cartão próprio!
Cartões aceitos: Visa, Mastercard, American Express internacionais. Cartões somente nacionais podem ser rejeitados.
🔧 Troubleshooting — Coexistência
1. Número Não Elegível
"Número não elegível"
Seu número de telefone não é elegível para se conectar à Plataforma WhatsApp Business.
O que significa: o número é muito recente no WhatsApp Business. A Meta exige um tempo mínimo de atividade.
O que fazer:
- Use o número normalmente por 7 a 60 dias antes de tentar conectar
- Não exclua e recrie a conta — isso reinicia o tempo de atividade
- Se o número já esteve em outra API antes: aguarde 1–2 meses
2. País Não Suportado
Causa: Meta restringiu temporariamente para certos países (Nigéria, África do Sul).
Solução: Brasil é suportado ✅ — nossos clientes não são afetados.
3. Número em Outra API
"Número já registrado em outra conta"
Este número está registrado em uma conta WhatsApp existente.
O que significa: o número estava (ou ainda está) conectado a outra plataforma de automação (Z-API, Evolution, 360dialog, etc.).
O que fazer:
- Desconectar do provedor anterior
- Remover o número do Business Manager da plataforma anterior
- Registrar novamente no WhatsApp Business App
- Usar ativamente por 1–2 meses antes de tentar
- Não tente reconectar antes de 24 horas
4. Falha na Sincronização
Solução:
- Manter app aberto e celular desbloqueado
- Wi-Fi estável
- Pode levar até 6 horas para grandes volumes
- Se falhar: reescanear QR Code
5. QR Code Não Funciona
Solução:
- Atualizar app para versão 2.24.17+
- Fluxo: Configurações → WhatsApp → Cadastre-se com o Facebook
- Verificar câmera
- Último recurso: reinstalar o app
6. Vinculação Facebook Falhou
Solução:
- Criar Página Facebook se não existir
- Verificar acesso de admin no BM e Página
- Verificar informações completas da conta
7. Dispositivos Não Compatíveis
| Compatível ✅ | NÃO Compatível ❌ |
|---|---|
| WhatsApp Web WhatsApp para Mac | WhatsApp para Windows WhatsApp para WearOS |
8. Nome da Empresa Travado
Após ativar a Coex, o nome fica travado. Atualizar antes da integração.
Checklist Rápido de Diagnóstico
| Verificação | Ação |
|---|---|
| App atualizado? | Versão 2.24.17+ |
| Número ativo há 7+ dias? | Usar ativamente antes de tentar |
| País suportado? | Brasil ✅ |
| Número livre de outras APIs? | Desconectar primeiro, aguardar 24h |
| BM com Controle Total? | Verificar permissões |
| 2FA ativado? | Obrigatório para admin BM |
| Internet estável? | Wi-Fi recomendado |
| Celular desbloqueado? | Manter app aberto |
🔧 Troubleshooting — Problemas Gerais
Problemas de Conexão
- PIN expirado — gerar novo PIN (Configurações → Conta → Plataforma comercial)
- PIN inválido — verificar cada dígito, redigitar
- Popup não abre — verificar bloqueador de popups no navegador
- Número não aparece — número pode estar vinculado a outra conta Facebook
Problemas de Mensagens
- Mensagens não chegam — verificar conexão API no painel
- Templates rejeitados — ajustar conforme feedback da Meta
- Erro de pagamento — verificar cartão internacional cadastrado
Quando Escalar
Se o problema persistir após as verificações básicas, escalar para o suporte técnico com as seguintes informações:
- Screenshot do erro
- Número de telefone afetado
- BM ID
- WABA ID
- Passos já tentados