WhatsApp Cloud API (oficial Meta)

Atualizado em 27 ago 2026

O WhatsApp Cloud API é o WhatsApp oficial da Meta: status de entrega/leitura em tempo real e disparos por templates aprovados, com regras próprias da Meta. Você pode conectar de duas formas: um número dedicado que passa a operar só pelo CRM, ou o modo híbrido, em que o mesmo número fica na API e continua funcionando no app WhatsApp Business do celular.

Onde fica

Menu Marketing › WhatsApp Cloud API (configuração), Templates e Disparos; a caixa de entrada é o Inbox WhatsApp Cloud (Menu Gestão › Inbox WhatsApp Cloud).

Recurso liberado por etapas — pode aparecer como "em breve" para algumas licenças.

Conceitos importantes da Meta

Janela de 24h — você só pode mandar mensagem livre dentro de 24h após a última mensagem do cliente. Fora disso, só com template aprovado.
Templates — mensagens pré-aprovadas pela Meta para iniciar conversa fora da janela 24h. Têm status: rascunho, em análise, aprovado, rejeitado.
Status do número — qualidade GREEN/YELLOW/RED (a Meta penaliza número com muitas denúncias).

Como conectar seu número

Na tela WhatsApp Cloud API, ao conectar pela primeira vez você escolhe entre dois caminhos oficiais:

Número dedicado à API — o número passa a operar só pelo CRM (deixa de funcionar no app do WhatsApp). Indicado para um número novo ou exclusivo de atendimento.
Híbrido (manter o WhatsApp Business) — o mesmo número fica na API e continua no app WhatsApp Business do celular ao mesmo tempo.

Em qualquer caminho, você faz login no Facebook com a conta que administra sua conta WhatsApp Business (WABA) e autoriza as permissões. Ao voltar, número, templates e inbox aparecem automaticamente.

Use a conta do Facebook que tem acesso de administrador à sua conta de WhatsApp Business. Sem esse acesso, a Meta não mostra o número para autorizar.

Modo híbrido (manter o WhatsApp Business)

No modo híbrido (recurso "Coexistence" da Meta) o mesmo número fica ativo na API e no app WhatsApp Business ao mesmo tempo. Você continua respondendo pelo celular e as mensagens novas sincronizam nos dois lados.

Antes de começar:

O número precisa estar ativo no app WhatsApp Business (não no WhatsApp comum) há pelo menos 7 dias.
Tenha o celular com a câmera à mão para escanear o QR Code.

Passo a passo:

Na conexão, escolha "Conectar modo híbrido" e faça login no Facebook.
Escaneie o QR Code com o app WhatsApp Business (no app: Configurações › Aparelhos conectados › Conectar um aparelho).
Confirme o nome do negócio e o fuso horário.
Pronto — você segue atendendo pelo celular e as mensagens novas também chegam no Inbox WhatsApp Cloud.

O modo híbrido depende da homologação do app com a Meta estar concluída. Enquanto isso, o botão aparece como "disponível após homologação".

O que muda no híbrido:

Conversas antigas ficam no app (não são importadas); só as novas sincronizam.
Grupos não sincronizam com a API.
O envio em massa começa com um limite (~250 conversas iniciadas por dia) que cresce com o uso.

Para que as mensagens que você envia pelo celular (app WhatsApp Business) também apareçam no Inbox WhatsApp Cloud, o app precisa estar assinado nos campos de webhook smb_message_echoes e message_echoes. Sem isso, só as mensagens recebidas e as enviadas pelo CRM aparecem.

Passo a passo (número dedicado)

O CRM oferece dois caminhos — escolha pelo que você já tem hoje. Os dois abrem a mesma janela da Meta; o que muda é o que você seleciona lá dentro, e é justamente aí que a conexão costuma se perder.

Ainda não tenho API oficial — você nunca usou a API da Meta e vamos criar a conta agora. Na janela da Meta: faça login no Facebook; em Conta do WhatsApp Business escolha Criar uma nova conta (não selecione nenhuma existente); informe o número e confirme o código que chegar por SMS ou ligação.

Já tenho API Oficial — o número já está na API, com a gente ou com outro sistema. Na janela da Meta: entre com a conta do Facebook que administra sua conta do WhatsApp Business; em Conta do WhatsApp Business selecione a conta que já existe (criar outra coloca o número na conta errada); e marque TODAS as contas e números que quer usar no CRM — ou "todas as atuais e futuras". Conta desmarcada não sincroniza templates nem números, e o CRM não recebe as mensagens dela. Se o número estiver ativo em outro sistema, desconecte lá antes.

Depois de conectar:

Confira se o número aparece na lista com o webhook ativo.
Crie templates e aguarde a aprovação da Meta.
Faça disparos usando templates aprovados. Ao montar a lista de quem recebe, o modo Avançado filtra os leads da carteira por corretor, origem, funil e etapa, etiquetas (com e sem), tipo e referência do imóvel, data de cadastro e faixa de preço. Marcando Somente proprietários, o público passa a ser os donos de imóvel ativo no site (não os leads) — os filtros de lead somem e ficam o recorte "imóvel sem atualização há mais de X dias", o bloco Do imóvel (cidade, bairros, tipo, categoria e empreendimento) e o limite; a mensagem de cada dono cita o imóvel dele que casou com esse recorte. O disparo também pode chegar aqui já pronto: veja abaixo.
Atenda as respostas no chat.

Disparo que vem do Radar do imóvel

Quem usa o Radar do imóvel (Editar imóvel › Radar) e escolhe sair pelo WhatsApp Oficial cai neste assistente com tudo preenchido:

Quem recebe — os clientes compatíveis marcados no Radar já vêm na lista, e o imóvel fica vinculado ao disparo. Um aviso no topo mostra quantos vieram.
Quando o lead responder — antes de sair do Radar, o passo 3 pergunta o que o sistema faz com quem responder. São quatro opções:
- Ativar IA — o assistente assume a conversa, apresenta o imóvel e busca a visita. Precisa de pelo menos um assistente ativo em Gestão › Assistentes.
- Notificar o corretor — o corretor do lead recebe um aviso no WhatsApp com a ficha do imóvel e o link do atendimento.
- Reenviar pra roleta — o lead volta para a distribuição e cai para o corretor da vez (roleta geral ou uma fila específica).
- Disparo simples — nada além do envio; quem responder aparece no atendimento, como sempre. Escolhendo uma das três primeiras, o sistema monta o robô sozinho com aquele imóvel e aquela reação, liga e o assistente já abre com ele selecionado em Enviar para automação — o aviso no topo diz qual robô é e qual modelo ele usa no primeiro envio. Não há nada a montar à mão.
O robô manda o modelo novidade_imovel_destaque (foto do imóvel no topo) com três botões de um toque:
- Quero saber mais e Agendar visita levam à reação que você escolheu. Com a IA, cada botão dá uma ordem diferente ao assistente: "quero saber mais" abre a conversa apresentando o imóvel; "agendar visita" já parte para propor dia e horário, porque quem tocou ali não quer ouvir a apresentação de novo.
- Não tenho interesse apenas etiqueta o lead — ninguém é incomodado depois.
- Sem resposta em 1 hora, o lead ganha a etiqueta de quem não respondeu, para o corretor trabalhar depois.
Imóvel sem preço cadastrado (venda sob consulta) não trava o disparo: o valor sai como "Sob consulta". Antes, o modelo era recusado pela Meta e aquele cliente simplesmente não recebia a mensagem.
Qual modelo — o assistente abre no modelo novidade_imovel_destaque, o de destaque de imóvel que o sistema instala em toda conexão nova (é o mesmo do robô "Disparo: imóvel em destaque"). Ele é procurado pelo nome, dentro da conta do número escolhido: cada conta tem a sua cópia aprovada. Se esse modelo não estiver aprovado nesse número, o aviso diz isso e você escolhe outro — os dados do imóvel entram nas variáveis do mesmo jeito.
O que vai na mensagem — as variáveis do modelo já vêm apontando para os dados daquele imóvel: nome do cliente, descrição (tipo, bairro e cidade), valor e link do anúncio. Quando o modelo tem cabeçalho de imagem, a foto de destaque do imóvel entra nele automaticamente. Se o imóvel for só de locação, o valor usado passa a ser o de locação (o preço de venda sairia em branco e a Meta recusaria a mensagem).
Conferência — ao lado da prévia aparece um cartão com a foto e a referência do imóvel, e a prévia mostra a mensagem exatamente como o cliente vai receber. No Oficial nenhum texto é enviado solto: quem abre a conversa é sempre o modelo aprovado, e o conteúdo do imóvel entra pelas variáveis dele.

Quando o robô é adotado, o modelo do primeiro envio sai dele — não há template a escolher no passo 2, só conferir. Se o robô não puder ser preparado (nenhum assistente de IA ativo, modelo ainda não aprovado naquela conta, envio por robô não liberado para a imobiliária), o aviso no topo explica o motivo e o disparo segue normalmente pelo modelo aprovado: nada do que você escolheu no Radar se perde.

Nada é enviado sozinho: você revisa o passo 2, confirma o ritmo no passo 3 e a campanha ainda nasce como Rascunho, esperando o Disparar agora.

Ao criar ou editar um template, e também ao escolher o template no disparo, o CRM mostra à direita uma prévia estilo WhatsApp: o balão da mensagem enviada com cabeçalho, corpo (negrito, itálico, tachado e quebras de linha), rodapé e botões, exatamente como o cliente vai ver. As variáveis já aparecem preenchidas com valores de exemplo (nome do lead, referência e preço do imóvel, link do catálogo, data de hoje). No disparo, a prévia atualiza ao vivo conforme você mapeia cada variável; o que ainda não foi mapeado fica destacado como {{1}} para você não esquecer. Quando o disparo vem do Radar do imóvel, a prévia usa os dados reais daquele imóvel — inclusive a foto de destaque no cabeçalho — em vez dos exemplos.

Problemas comuns

A tela de Templates lista mensagens, mas a Visão geral diz "nenhuma conta conectada" — não é erro. Os templates ficam salvos no CRM depois que um número foi conectado uma vez; eles continuam aparecendo mesmo após a conexão ser desconectada. A Visão geral mostra o estado atual (sem número ativo). Para criar, editar ou disparar, reconecte um número — os templates do histórico voltam a funcionar.
Conectei na Meta mas o número não aparece no CRM — a conexão só entra quando a janela da Meta termina dentro do CRM. Se a janela foi fechada antes do fim, ou a conexão foi concluída direto no painel da Meta, o CRM não recebe a confirmação. Refaça pelo botão "+ Conectar meu WhatsApp" e deixe a janela terminar sozinha; depois clique em "Verificar conexão".
Mensagem fora da janela 24h não enviou — use um template aprovado; mensagem livre só dentro da janela.
Template rejeitado — a Meta recusou o texto; ajuste conforme as políticas e reenvie.
Qualidade do número caiu (YELLOW/RED) — muitas denúncias; reduza disparos e fale só com quem espera contato.
Apareceu "Embedded signup is only available for BSPs or TPs" — esse aviso vem da Meta enquanto a homologação do app ainda está em andamento. A conexão usa o login padrão do Facebook, que funciona normalmente; basta seguir pelo botão "+ Conectar meu WhatsApp".
Aviso "Número não verificado na Meta" — o cadastro do número na Meta não foi concluído: falta confirmar o código de verificação (SMS ou ligação). Enquanto isso, o WhatsApp Oficial não recebe nem envia mensagens nesse número. O dono da conta resolve em business.facebook.com → WhatsApp Manager → o número → Verificar, informando o código recebido; depois clique em "Sincronizar com a Meta" na tela WhatsApp Cloud API para o CRM atualizar o status.
Aviso "Mensagens não estão chegando ao CRM" (webhook recusado) — a Meta recusou a inscrição do webhook da sua conta, então nenhuma mensagem recebida chega ao CRM: o lead não é salvo e não aparece no atendimento, mesmo com o número aparecendo como conectado. A causa mais comum é a conta oficial estar conectada também a outro sistema de atendimento: nesse caso a Meta deixa o controle com o outro aplicativo — o CRM lê os dados (templates, status do número), mas não recebe nem envia. Um número oficial funciona em um sistema de cada vez. Para resolver: (1) desconecte o número e a conta do WhatsApp Business do outro sistema; (2) em business.facebook.com → Configurações do negócio → Contas do WhatsApp Business → sua conta, remova o aplicativo do outro sistema dos ativos conectados; (3) reconecte no CRM em Marketing › WhatsApp Cloud API pelo caminho "Já tenho API Oficial" (marcando todas as contas) e clique em "Sincronizar com a Meta". Prefere manter o outro sistema? Use um número diferente dedicado ao CRM: conecte por "Ainda não tenho API oficial" criando uma conta nova. Quando o aviso listar pendências na sua conta (verificação do número, nome de exibição, cobrança), resolva primeiro esses itens em business.facebook.com → WhatsApp Manager e sincronize — quando a Meta aceitar, o aviso some sozinho. Persistindo depois de tudo isso, é caso de abrir suporte com a Meta informando o ID da conta do WhatsApp Business — houve casos em que a própria Meta devolve erro interno nesse endereço e nada do lado do CRM resolve.
Aviso "Envio com limite reduzido" — a Meta liberou o recebimento, mas limitou quantas conversas novas você inicia por dia. O motivo mais comum é o nome de exibição ainda não aprovado: a aprovação é da Meta, costuma sair em algumas horas e o limite sobe sozinho. Acompanhe em business.facebook.com → WhatsApp Manager → Números → o número → Nome de exibição. Receber mensagem não é afetado.
Erro no modo híbrido logo após o QR (ex.: "Invalid Auth Challenge") — é um erro de pareamento da própria Meta. Verifique: (1) atualize o app WhatsApp Business (versão recente); (2) escaneie o QR de dentro do WhatsApp Business (Configurações → Aparelhos conectados); (3) recomece o fluxo do zero e escaneie rápido — o QR expira em segundos; (4) o número precisa estar no app Business há 7+ dias e não estar já conectado à API em outro lugar.

Perguntas frequentes

Qual a diferença para o assistente por QR Code? O assistente por QR usa um número comum conectado como WhatsApp Web (não oficial); o Cloud é a API oficial da Meta, com regras de template e janela de 24h. No Cloud, o número dedicado é registrado direto (sem QR) e o modo híbrido usa um QR só para vincular o app WhatsApp Business — diferente do QR do WhatsApp Web.

Posso usar o mesmo número na API e continuar no WhatsApp do celular? Sim, com o modo híbrido (Coexistence) — desde que o número esteja no app WhatsApp Business (não no WhatsApp comum). Veja a seção "Modo híbrido" acima.

O popup não conclui. Existe outra forma de conectar? Sim, para administradores há "Conectar via token" (em Detalhes técnicos (admin) na tela do WhatsApp Cloud API), que conecta uma conta direto pelos WABA ID + Phone Number ID, sem o popup. Pré-requisito na Meta: a conta WhatsApp (WABA) precisa estar atribuída ao Usuário do Sistema dono do token — em Configurações da Empresa → Usuários do sistema → Adicionar ativos → Contas do WhatsApp → controle total. Sem essa atribuição, a Meta responde "Missing Permission" e a conexão não entra.