Pular para o conteúdo

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?.

Antes de começar, você precisa de:

  1. Conta no Meta Business Manager (business.facebook.com)
  2. WhatsApp Business Account (WABA) criada dentro do Business Manager
  3. 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
  4. Acesso a um SMS ou ligação para validar o número
  5. 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)

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.

  1. Acesse developers.facebook.com/apps.
  2. Clique em Criar app → Empresa → preencha o nome do app (ex: “app.smart Integração”).
  3. Após criado, adicione o produto WhatsApp ao app.
  4. Vincule o app à sua WhatsApp Business Account existente.

A Meta oferece um token temporário (24h) e exige troca por um token permanente para uso em produção.

  1. Em WhatsApp → Configuração da API, copie o token temporário e o ID do número de telefone.
  2. Vá em Configurações de Negócio → Usuários do sistema → Adicionar.
  3. Crie um usuário do sistema com papel de Administrador.
  4. Gere um token de acesso permanente para esse usuário com a permissão whatsapp_business_messaging.
  5. Salve o token em local seguro — só é exibido uma vez.
  1. No painel do app.smart, acesse Config. → Caixas de Entrada → Adicionar Caixa de Entrada.
  2. Selecione WhatsApp.
  3. Escolha o provedor WhatsApp Cloud (Meta).
  4. 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)
  5. Clique em Criar Caixa de Entrada.

O app.smart precisa receber notificações da Meta quando uma mensagem chegar.

  1. Após criar o inbox, copie a URL de webhook e o Verify Token que o app.smart exibe na tela.
  2. Na Meta, acesse WhatsApp → Configuração → Webhooks → Configurar.
  3. Cole a URL e o Verify Token. Clique em Verificar e salvar.
  4. Em Campos de webhook, inscreva-se em pelo menos: messages, message_status, message_template_status_update.
  1. Envie uma mensagem do seu celular pessoal para o número configurado.
  2. Aguarde até 30 segundos.
  3. Verifique se a conversa aparece em Conversas no app.smart.
  4. Responda pela interface e confirme se a mensagem chega no celular.

Se algo falhar, consulte Troubleshooting — WhatsApp desconectou.

Conectar WhatsApp Cloud API: a aba Templates da caixa de WhatsApp, com a lista e os status de aprovação

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).

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.

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.

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.

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.