WhatsApp Cloud API com Embedded Signup da Meta

Visão geral

A conexão guiada abre a autorização da Meta e vincula o número escolhido à caixa de WhatsApp Cloud. Para criar uma caixa, o recurso WhatsApp Embedded Signup Flow precisa estar habilitado na conta, tanto em instalações próprias quanto na nuvem. A instalação também precisa ter o aplicativo da Meta configurado. Um administrador ou perfil nativo autorizado a gerenciar caixas, com escopo adequado, pode executar o fluxo.

Pré-requisitos

• Permissão para gerenciar a caixa e escopo de acesso adequado.
• Aplicativo da Meta configurado na instalação e acesso à empresa que administra o número.
• Para criar uma caixa, WhatsApp Embedded Signup Flow habilitado na conta. Para transferência manual, WhatsApp Manual Transfer habilitado.
• A recuperação de uma caixa existente usa a autorização de gerenciamento dessa caixa.

Passo a passo

1. Abra Configurações → Caixas de Entrada → Adicionar caixa → WhatsApp.
2. Escolha a conexão guiada com a Meta e entre na conta empresarial que administra o número.
3. Selecione a WABA e o número correto; conclua as etapas solicitadas pela Meta.
4. Aguarde a plataforma confirmar a configuração. Fechar a janela ou receber apenas parte da autorização não conclui a conexão.
5. Envie e receba uma mensagem de teste em um contato próprio antes de iniciar a operação.

Configurações & opções

Reconectar ou reconfigurar uma caixa existente

Abra Configuração → Reconfigurar ou use o aviso de reconexão da própria caixa. A recuperação permanece disponível ao administrador autorizado mesmo quando a criação de novas caixas ou a flag legada de reconfiguração está desligada. Não crie outra caixa para recuperar a conexão existente.

Selecione o mesmo número. A recuperação preserva a caixa, conversas e parceiro WhatsApp Web do híbrido. Um identificador que pertença a outro número será recusado. Coex usa esse mesmo fluxo guiado.

Se aparecer configuração pendente, as credenciais foram salvas, mas a plataforma ainda não confirmou toda a configuração necessária. A caixa continua disponível para uma nova tentativa de recuperação. Não interprete essa mensagem como conexão concluída nem repita a criação de caixas. A mensagem indica a etapa que ficou pendente — registro do número ou entrega de mensagens (webhook) — e a nova tentativa é feita pelo aviso de reconexão da caixa.

Interpretar a saúde da conta

A aba Saúde da conta mostra o que a Meta informa hoje sobre o número. O topo diz quando a Meta confirmou os dados pela última vez (Verificado com a Meta em). Verificar agora consulta a Meta de novo; a plataforma faz essa consulta no máximo uma vez a cada 30 segundos por caixa, e o botão fica desativado nesse intervalo.

• Situação de envio: o estado que a Meta calcula antes de cada mensagem, considerando o número, a conta do WhatsApp Business, o portfólio empresarial e o app: Disponível, Limitado ou Bloqueado. Quando algo limita ou bloqueia, a aba mostra o item afetado, a explicação da Meta e o que fazer, com as palavras da própria Meta. Os avisos que a Meta anexa a um item também aparecem, mesmo com o item disponível; o mais grave é "o app não está assinado no webhook de mensagens", que significa que o número não recebe as mensagens dos clientes. A linha Receber ligações por SIP mostra Não configurado quando o número não usa SIP, o que é normal na plataforma.
• Pontos de atenção: avisos que a plataforma registra a partir das notificações da Meta. Número reconectando depois de uma troca de aparelho, conexão removida, autorização que precisa ser refeita, restrições em vigor com a data de término, violação de política, conversas com outro responsável no Conversation Routing, eventos da conta ou mensagens entregues em outro endereço e caixa conectada há mais de 24 horas sem receber nenhuma mensagem. Os avisos de conexão levam a Ir para Configuração.
• Número: número, nome exibido e status do nome, plataforma (só Cloud API, ou também o app WhatsApp Business), conta comercial oficial (selo azul), modo da conta (Produção ou Teste), status do número e verificação por código.
• Capacidade e limites: velocidade de envio, limite de mensagens, classificação de qualidade e, para quem pode ver custos, a estimativa de mensagens de serviço gratuitas do mês. Veja a próxima seção.
• Conta empresarial: conta do WhatsApp Business, portfólio, verificação da empresa e análise da conta.
• Webhook: o endereço configurado e os campos de webhook assinados no app da Meta: o app desta instalação numa caixa criada pelo Embedded Signup, ou o seu próprio app numa caixa manual com App Secret. Se o campo messages não estiver assinado, o app não recebe as mensagens dos clientes e a caixa fica em silêncio: a aba avisa isso primeiro. Sem App Secret, ou quando a Meta recusa o segredo, a lista vira um checklist para conferir no painel de apps da Meta. A aba também lista os apps assinados na conta do WhatsApp Business e avisa quando mais de um entrega os webhooks aqui. Se o callback do app aponta para outro sistema, a aba avisa: a Meta sempre entrega as atualizações da conta, os alertas e o status dos templates no callback do app, então esta instalação deixa de recebê-los.

Uma informação que a Meta não devolveu não derruba a aba: o bloco afetado avisa e mantém o último valor conhecido. Uma falha ao consultar a conta empresarial não apaga as informações do número que continuam válidas. O diagnóstico indica a etapa afetada e permite Tentar novamente.

Um erro de objeto indisponível ou permissão não prova, sozinho, que o token expirou. Confira o número, a WABA, as permissões e a etapa indicada; use Reconfigurar quando a autorização precisar ser refeita. O horário da consulta e a indicação de dados desatualizados ajudam a distinguir histórico de estado atual.

Capacidade e limites do número

Velocidade de envio. Quantas mensagens por segundo a Meta aceita deste número, somando as enviadas e as recebidas. O ritmo segue o limite do número na Meta: 80 mensagens por segundo no início, até 1.000 se a Meta liberar, e 20 num número de coexistência. As campanhas usam até o limite menos 5.

• A Meta sobe o número para o nível alto sozinha quando ele se qualifica: limite de mensagens ilimitado, pelo menos 100 mil clientes únicos fora de janela de atendimento em 24 horas e qualidade Média ou melhor. A plataforma lê o nível a cada 6 horas e atualiza na hora quando a Meta avisa o aumento.
• O bloco mostra Confirmada pela Meta em com a data e a hora da última confirmação.
• Quando a Meta ainda não confirmou o nível, ou a última confirmação tem mais de 24 horas, o bloco diz isso e usa o limite padrão de 80. A plataforma nunca supõe o nível alto sem a confirmação.
• Nada é reservado para as respostas: elas usam a mesma folga dos outros envios. Enviar acima do limite faz a Meta recusar a mensagem.
• Uma caixa do WhatsApp Web não tem esse limite: ela segue o próprio controle de ritmo contra banimento.

Limite de mensagens. Quantos clientes diferentes podem receber mensagens fora da janela de atendimento num período móvel de 24 horas. O limite é do portfólio empresarial e vale para todos os números dele. A aba mostra uma estimativa do uso nas últimas 24 horas: clientes que receberam um template fora de uma janela de atendimento aberta pelos números desta conta conectados à ConversaLabs. Outros apps e contas no mesmo portfólio não entram na conta; use o valor como referência, não como o número oficial da Meta. Como o limite sobe, segundo a Meta:

1. de 250 para 2.000 depois de um caminho: verificar a empresa, pedir a verificação ao seu parceiro, ou entregar 2.000 mensagens fora de janelas de atendimento a clientes únicos em 30 dias, com templates de alta qualidade;
2. depois disso, a Meta sobe um nível (10 mil, 100 mil, ilimitado) em até 6 horas quando a qualidade das mensagens é alta e pelo menos metade do limite atual foi usada nos últimos 7 dias.

Classificação de qualidade. Alta, Média, Baixa ou Sem classificação, conforme os clientes receberam as mensagens do número nos últimos dias. A Meta não informa a data de uma mudança de qualidade; a aba mostra a última mudança observada pela plataforma entre duas verificações.

Mensagens de serviço gratuitas. O bloco usa uma franquia mensal estimada de 1.000 mensagens de serviço por número. Franquia mensal estimada; a Meta não publica esse limite na documentação acompanhada. Mostra o uso e o saldo estimados com base nas confirmações de entrega da Meta, que não confirmam esse limite, e leva à aba Custos. Ele aparece só para quem pode ver os custos do WhatsApp.

Alternar para configuração manual

O recurso WhatsApp Manual Transfer precisa estar habilitado. Essa transição atende caixas Cloud fora de Coex: a plataforma verifica na Meta se o número já não usa o Business App, se os novos identificadores representam o mesmo telefone e se não existe pareamento híbrido. Um resultado incompleto de saúde não libera a operação.

1. Configure o webhook no seu app da Meta antes de migrar. A Meta só entrega as mensagens do número por um app que tenha o webhook do WhatsApp configurado; sem ele, a migração é recusada. No App Dashboard do seu app, abra WhatsApp → Configuração (ou Casos de uso → Personalizar → Configuração, se o app foi criado pelo caso de uso de WhatsApp) e:

• em URL de callback, cole a URL que o assistente mostra para este número;
• em Verificar token, cole o token de verificação desta caixa, também mostrado no assistente, e clique em Verificar e salvar;
• em Campos do webhook, assine messages (e calls, se a caixa recebe ligações). Assine também os recomendados: account_update, smb_message_echoes, history, smb_app_state_sync, message_template_status_update, message_template_quality_update, template_category_update e user_preferences;
• deixe o app no modo Ao vivo: no modo Desenvolvimento, a Meta não envia alguns webhooks.

2. Rode o assistente. Abra Iniciar migração manual no aviso da caixa e siga as etapas: dados da empresa (ID da WABA e do número), token de acesso permanente de Usuário do Sistema, Chave secreta do app (opcional e recomendada), Webhook do seu app da Meta (copie a URL e o token e confirme que configurou) e revisão.

3. A plataforma confere tudo antes de salvar. Com o token informado, ela verifica na Meta o app dono do token, se ele não expira, se tem whatsapp_business_management e whatsapp_business_messaging para esta conta do WhatsApp Business e se a URL de callback do app aponta para esta instalação — atualizações de template e alertas da conta sempre vão para essa URL. Com a Chave secreta, confere também se ela pertence ao app e se messages está assinado. Mesmo sem a Chave secreta, quando a Meta avisa que o app não está assinado no webhook de mensagens, a migração é recusada. Se algo faltar, nada é salvo e a mensagem diz o que configurar, com o nome do app.

Chave secreta do app. Fica em Configurações do app → Básico. Com ela, a plataforma configura sozinha o webhook do WhatsApp do seu app durante a migração (URL de callback desta instalação, token de verificação e campos do webhook, incluindo messages), e o passo 1 vira só referência. Se o seu app já envia os webhooks para outro sistema, nada é alterado: a migração é recusada e a mensagem mostra o endereço atual. Com ela, a assinatura de cada webhook do seu app também é conferida; sem ela, os webhooks do app são aceitos sem essa verificação, e a aba Saúde da conta avisa. Depois de salva, ela não é exibida de novo.

Transferência pendente. Se a Meta recusar a configuração depois que as credenciais foram salvas, a caixa mostra o aviso Transferência manual pendente com a causa. Quando a Meta recusa porque o app não tem webhook assinado em messages, o aviso nomeia o app e mostra a URL a configurar. Corrija no App Dashboard e use Tentar transferência novamente, informando o token outra vez. Com o registro automático de webhook ativo, a nova tentativa refaz a configuração mesmo quando a Meta não responde à verificação prévia. Se a plataforma não conseguir consultar a Meta no momento, nada é alterado e a mensagem pede para tentar novamente em alguns minutos.

4. Remova o app anterior. Depois da migração, o app da instalação continua assinado na conta do WhatsApp Business e entrega os mesmos webhooks que o seu app: eles chegam em dobro. Em Saúde da conta → Webhook, a plataforma lista os apps assinados e mostra a ação Remover o app. Antes de remover, ela confere na Meta que o seu app está assinado e entrega este número aqui, que nenhuma outra caixa da mesma conta depende do app anterior e que a entrega foi provada: um webhook assinado com a sua Chave secreta chegou depois da migração ou, sem Chave secreta, você confirma que uma mensagem de teste chegou na caixa. A Meta para de entregar ao app anterior na hora; você pode desfazer a remoção por 72 horas. Quando a plataforma não puder mais remover o app por você, o aviso pede para removê-lo da conta do WhatsApp Business nas ferramentas da Meta.

Para recuperar Coex ou uma caixa híbrida, use Reconfigurar. A transferência manual não desfaz o pareamento nem troca silenciosamente o número atendido.

Número que outro parceiro já usa

No modelo de contas da Meta em vigor desde setembro de 2026, não existe mais migração de número entre parceiros. Para trazer para a plataforma um número que hoje é atendido por outro parceiro do WhatsApp:

1. O cliente compartilha com a plataforma a conta do WhatsApp dona do número, pelo próprio Embedded Signup (escolhendo esse número) ou pelo Meta Business Suite. O número não muda de lugar e as conversas continuam.
2. O parceiro anterior continua no número até o cliente removê-lo no Meta Business Suite.
3. Com dois parceiros no número, a Meta roteia cada conversa para um único responsável. Peça ao cliente para abrir Conversation Routing no Meta Business Suite e definir a plataforma como responsável principal das entradas que a equipe vai atender (por exemplo, Atendimento).
4. Até isso acontecer, a caixa nova pode ficar sem mensagens recebidas, mesmo com a conexão concluída.

A primeira tela da Meta pede o número antes de qualquer outra escolha. Se o número já estiver em uso no app WhatsApp Business, a Meta abre sozinha o fluxo de coexistência.

Casos de uso

• Conectar pela primeira vez um número Cloud à plataforma.
• Renovar a autorização de uma caixa Cloud ou Coex preservando atendimento e histórico.
• Migrar uma caixa Cloud elegível para uma aplicação Meta gerenciada manualmente.

Dicas, limites e boas práticas

• Confirme o número e a WABA antes de concluir a autorização.
• Preserve a caixa existente durante uma recuperação; criar outra pode separar o histórico.
• Depois de configurar ou recuperar, teste envio e recebimento em um contato próprio. A indicação de configuração pendente exige completar a etapa indicada.

Solução de problemas

• A janela foi cancelada ou expirou: inicie novamente o fluxo da mesma caixa.
• A opção de criação não aparece: confira a habilitação do recurso e a configuração do aplicativo.
• Não consegue recuperar uma caixa: confira a permissão de gerenciar essa caixa e seu escopo.
• Configuração pendente: repita a recuperação; confirme o webhook e teste o recebimento real.
• A migração foi recusada porque o app não tem webhook: configure a URL de callback, o token de verificação e o campo messages no App Dashboard do app indicado e tente de novo. Nada foi salvo.
• A Chave secreta foi recusada: copie-a de Configurações do app → Básico do mesmo app do token, ou deixe o campo vazio.
• Mensagens e eventos chegam em dobro depois da migração: o app anterior ainda está assinado. Remova-o em Saúde da conta → Webhook.
• Número diferente: selecione o número já vinculado à caixa; não reutilize a recuperação para substituí-lo.
• A caixa foi conectada, mas não recebe mensagens: o número provavelmente ainda tem outro parceiro como responsável principal. Peça ao cliente para ajustar o Conversation Routing no Meta Business Suite.
• Situação de envio Limitado ou Bloqueado: siga O que fazer no item indicado. Os textos vêm da Meta; depois de corrigir no WhatsApp Manager, use Verificar agora.
• Velocidade de envio Não confirmada: a Meta não confirmou o nível nas últimas 24 horas. Use Verificar agora; enquanto isso, vale o limite padrão de 80 mensagens por segundo.

Veja também

• Roteamento de conversas do WhatsApp: Agente da Meta e outros parceiros
• Coexistence do WhatsApp Cloud
• Caixa híbrida do WhatsApp