A WhatsApp Cloud API é a integração oficial da Meta. Diferente do método via QR Code, a Cloud API permite enviar templates pré-aprovados (mensagens HSM) pra abrir conversa fora da janela de 24h, tem entrega oficial garantida pela Meta e foi pensada pra alto volume.
Mensagens são espelhadas via echoes.
⚠️ Atenção: a Cloud API ainda está em BETA no Syncro. Se você não vê o card "WhatsApp Cloud API" no painel de Integrações, é porque essa funcionalidade ainda não foi liberada pra sua conta. Se precisar de acesso antecipado, entre em contato com o suporte.
Pré-requisitos
- Estar logado com permissão de admin.
- Feature flag
whatsapp_cloud_apihabilitada pra sua conta (definida pelo time Syncro). - WhatsApp Business app versão 2.24.17 ou superior instalado no celular.
- Número ativo no WhatsApp Business há pelo menos 7 dias.
- País suportado pela Meta: Brasil ✅, Estados Unidos, México, Índia, Indonésia, Hong Kong, Singapura, entre outros.
Diferenças vs QR Code
| Aspecto | QR Code | Cloud API (oficial) |
|---|
| Templates HSM | Não | Sim (obrigatório pra abrir conversa fora da janela 24h) | | Janela 24h | Não tem | Tem (regra Meta) | | Listagem de grupos | Sim | Não (Meta não expõe) | | Throughput | Limitado | 20 mensagens/segundo | | Estabilidade | Pode cair se celular for desligado | Sessão permanente | | Cobrança Meta | Grátis | Cobrança por categoria de template/conversa |
Pra um número novo de prospecção em massa, recomendamos Cloud API. Pra atendimento conversacional do dia a dia, o QR Code é suficiente.
Passo a passo
- No menu lateral, acesse Configurações → Integrações.
- Localize o card WhatsApp Cloud API com o badge BETA.
- Clique em Conectar com Meta.
- Faça login na sua conta Facebook (use a conta que administra o seu Meta Business).
- Selecione (ou crie) o Business Manager que vai gerenciar essa integração.
- Selecione o WhatsApp Business Account (WABA) ou crie um novo.
- Escolha o número de telefone:
- Se não, você cadastra um número novo e recebe o código de verificação por SMS ou ligação.
- Confirme as permissões solicitadas pela Meta.
- Aguarde o popup fechar. O Syncro recebe os dados (
phone_number_id,waba_id,business_id) e finaliza o vínculo automaticamente. - O card agora mostra o número como Conectado.
Adicionar mais de um número
Você pode conectar vários números à mesma conta. No card Cloud API, clique em Adicionar outro número e repita o fluxo. Cada número conta pro limite do seu plano.
O que muda na operação do dia a dia
Depois de conectar via Cloud API, alguns comportamentos mudam:
- Janela de 24h: você só pode mandar mensagem livre pro cliente nas primeiras 24h depois de ele ter te respondido. Fora disso, é template aprovado. Veja A janela de 24h explicada.
- Templates HSM: você precisa criar e submeter templates pra Meta aprovar antes de poder usar pra abrir conversas. Veja Templates HSM (Cloud API).
- Sem listagem de grupos: a API da Meta não suporta listar grupos pra envio. Pra disparar mensagem em grupo, use uma instância paralela.
Token de acesso e saúde da integração
A Cloud API depende de um token de acesso válido pra continuar funcionando. O Syncro verifica diariamente se o token está saudável (cron whatsapp:cloud-token-health) e te notifica antes de qualquer expiração:
- Válido ✅ — tudo funcionando normalmente
- Expirando em breve ⚠️ — você recebe um aviso por email/dashboard
- Expirado ❌ — mensagens não são entregues; você precisa reconectar
Se aparecer alerta de expiração, vá em Configurações → Integrações e clique em Reconectar no card.