Conectar WhatsApp Cloud API
O WhatsApp Cloud API é a forma oficial de integrar números de WhatsApp Business a plataformas de atendimento, mantida diretamente pela Meta. É a opção recomendada para empresas que exigem máxima estabilidade, conformidade com as políticas do WhatsApp e suporte a templates aprovados (HSM) para disparos.
Ainda escolhendo entre o oficial e o Web? A comparação completa — custo, riscos, prós e contras — está em WhatsApp oficial ou WhatsApp Web?.
Pré-requisitos
Seção intitulada “Pré-requisitos”Antes de começar, você precisa de:
- Conta no Meta Business Manager (business.facebook.com)
- WhatsApp Business Account (WABA) criada dentro do Business Manager
- Número de telefone: um número novo, ou o número que já está no aplicativo WhatsApp Business — este entra pela coexistência, pelo caminho curto abaixo, sem sair do celular
- Acesso a um SMS ou ligação para validar o número
- Verificação da empresa na Meta: não é obrigatória para começar, mas é o caminho mais curto para o limite de envio subir (veja limites)
O caminho curto: conexão pela Meta
Seção intitulada “O caminho curto: conexão pela Meta”Antes do passo a passo manual, saiba que existe um atalho, e ele é o caminho recomendado.
Em Config. → Caixas de Entrada → Adicionar → WhatsApp, a primeira opção é WhatsApp Business: um fluxo em que você entra com a sua conta da Meta numa janela deles e autoriza. Pronto.
O que esse fluxo resolve sozinho:
- Nenhuma configuração manual — sem copiar id de número, id de conta ou token
- Autenticação por OAuth, sem token permanente colado em campo
- Webhook e número configurados automaticamente
- Coexistência: a janela da Meta oferece conectar o número que já está no aplicativo WhatsApp Business. Ele continua no celular, e o que for respondido pelo aplicativo aparece na conversa aqui. Detalhes em coexistência
Use o caminho manual descrito abaixo só quando o número já está conectado à Plataforma WhatsApp Business por outro meio, ou quando o fluxo rápido não está disponível na sua conta. A própria tela oferece o link para o modo manual.
Passo a passo manual
Seção intitulada “Passo a passo manual”1. Criar app na Meta
Seção intitulada “1. Criar app na Meta”- Acesse developers.facebook.com/apps.
- Clique em Criar app → Empresa → preencha o nome do app (ex: “app.smart Integração”).
- Após criado, adicione o produto WhatsApp ao app.
- Vincule o app à sua WhatsApp Business Account existente.
2. Obter token permanente
Seção intitulada “2. Obter token permanente”A Meta oferece um token temporário (24h) e exige troca por um token permanente para uso em produção.
- Em WhatsApp → Configuração da API, copie o token temporário e o ID do número de telefone.
- Vá em Configurações de Negócio → Usuários do sistema → Adicionar.
- Crie um usuário do sistema com papel de Administrador.
- Gere um token de acesso permanente para esse usuário com a permissão
whatsapp_business_messaging. - Salve o token em local seguro — só é exibido uma vez.
3. Configurar inbox no app.smart
Seção intitulada “3. Configurar inbox no app.smart”- No painel do app.smart, acesse Config. → Caixas de Entrada → Adicionar Caixa de Entrada.
- Selecione WhatsApp.
- Escolha o provedor WhatsApp Cloud (Meta).
- Preencha:
- Nome do inbox (ex: “WhatsApp Comercial”)
- Número de telefone (formato internacional, ex:
+5511999990000) - ID do número de telefone (copiado no passo 2)
- ID da conta WhatsApp Business (encontrado em Configuração da API)
- Token de acesso permanente (gerado no passo 2)
- Clique em Criar Caixa de Entrada.
4. Configurar webhook
Seção intitulada “4. Configurar webhook”O app.smart precisa receber notificações da Meta quando uma mensagem chegar.
- Após criar o inbox, copie a URL de webhook e o Verify Token que o app.smart exibe na tela.
- Na Meta, acesse WhatsApp → Configuração → Webhooks → Configurar.
- Cole a URL e o Verify Token. Clique em Verificar e salvar.
- Em Campos de webhook, inscreva-se em pelo menos:
messages,message_status,message_template_status_update.
5. Validar funcionamento
Seção intitulada “5. Validar funcionamento”- Envie uma mensagem do seu celular pessoal para o número configurado.
- Aguarde até 30 segundos.
- Verifique se a conversa aparece em Conversas no app.smart.
- Responda pela interface e confirme se a mensagem chega no celular.
Se algo falhar, consulte Troubleshooting — WhatsApp desconectou.
Templates HSM (mensagens fora da janela 24h)
Seção intitulada “Templates HSM (mensagens fora da janela 24h)”
A Meta permite o envio livre apenas dentro de 24 horas após a última mensagem do cliente. Fora desse período, você só pode enviar templates pré-aprovados (HSM — Highly Structured Message).
O modelo nasce aqui, não no Gerenciador da Meta
Seção intitulada “O modelo nasce aqui, não no Gerenciador da Meta”Esta é a parte que costuma surpreender quem vem de outra ferramenta: o app.smart tem construtor próprio de modelo, e é por ele que o modelo vai para aprovação da Meta.
Você monta o modelo no app — com pré-visualização, botões, carrossel e variáveis — e envia para aprovação dali mesmo. Não precisa abrir o Gerenciador da Meta.
O passo a passo está em templates de WhatsApp.
Usar o modelo na conversa
Seção intitulada “Usar o modelo na conversa”Quando a janela de 24 horas fecha, a caixa de resposta troca o campo de texto por escolher um template. Só aparecem os aprovados.
Os modelos da caixa ficam em Config. → Caixas de Entrada → a caixa → aba Templates.
Limites e tiers de envio
Seção intitulada “Limites e tiers de envio”A Meta limita quantas pessoas diferentes a empresa pode chamar por modelo em 24 horas, fora da janela de atendimento. O limite é do portfólio de negócios, somando todos os números dele. Responder quem escreveu não conta.
Pela página Messaging limits da Meta:
- Todo portfólio novo começa em 250.
- Vai para 2.000 por um destes caminhos: verificar a empresa na Meta, ser verificada pelo parceiro que conectou o número, ou entregar 2.000 mensagens fora da janela de atendimento, para números diferentes, em 30 dias, com modelos de qualidade alta.
- Daí para cima (10 mil, 100 mil, ilimitado), sobe sozinho, um nível por vez: basta a qualidade estar alta e você ter usado pelo menos metade do limite nos últimos 7 dias.
A qualidade não faz o limite descer: com qualidade baixa, ele só para de subir. O que a qualidade ruim — muitos bloqueios e denúncias — pode trazer é a Meta limitar ou bloquear os envios do número. A qualidade e esse aviso estão na saúde da conta.
Dúvidas comuns
Seção intitulada “Dúvidas comuns”Posso conectar o mesmo número à Cloud API e ao app WhatsApp no celular? Pelo caminho curto (login da Meta), sim, se o número estiver no aplicativo WhatsApp Business: é a coexistência. Pelo passo a passo manual, não: o número não pode estar em aplicativo nenhum.
Quanto custa o WhatsApp Cloud API? A Meta cobra por mensagem entregue (desde julho de 2025), com valor por categoria — marketing, utilidade, autenticação — e por país. Desde 1º de outubro de 2026, responder dentro da janela de 24 horas também é cobrado depois das 1.000 respostas grátis por mês de cada número. O detalhe está em quanto custa, os valores em reais no guia de preço da API oficial do WhatsApp e a fonte na tabela oficial de preços.
Posso usar o mesmo token para múltiplos inboxes? Sim, se os números pertencerem à mesma WhatsApp Business Account. Cada inbox deve ter o ID do número correspondente.
Como receber confirmação de leitura? Vem sozinho. A mensagem mostra o estado — enviada, entregue, lida ou falhou — do mesmo jeito que no aplicativo.
O cliente envia um áudio — o app.smart transcreve? Transcreve, se a transcrição estiver ligada. Ela é configurada por assistente, no Brain, e não por um interruptor de conta. Veja gravar e enviar áudio.