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

| Nível | Limite da Meta | Campanhas disparam até |
|---|---|---|
| Padrão | 80 por segundo | 75 por segundo |
| Alta | 1.000 por segundo | 995 por segundo |
| Coexistência (número também no app WhatsApp Business) | fixo em 20 por segundo pela Meta | 15 por segundo |

- 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](/hc/ajuda/articles/inboxes-channels-whatsapp-conversation-routing-pt-br)
- [Coexistence do WhatsApp Cloud](/hc/ajuda/articles/inboxes-channels-whatsapp-coexistence-pt-br)
- [Caixa híbrida do WhatsApp](/hc/ajuda/articles/inboxes-channels-whatsapp-hybrid-inbox-pt-br)