Processo conexão do WhatsApp com Coexistência

Conectar um número em coexistência tem duas metades: o Embedded Signup, feito no computador dentro do painel, e uma autorização no celular, feita no aplicativo WhatsApp Business. A segunda metade é a que costuma pegar de surpresa — ela chega como uma mensagem da Meta no próprio WhatsApp e envolve uma decisão sobre o histórico de conversas que só pode ser tomada uma vez. O processo inteiro leva poucos minutos e o número não sai do ar.

Este guia é o procedimento. O que a coexistência é, o que ela permite e onde ela trava está em coexistência no WhatsApp.

Antes de começar

Quatro coisas precisam estar prontas. Faltando qualquer uma delas, o fluxo trava no meio:

1. O número tem que estar em uso no aplicativo WhatsApp Business, não no WhatsApp comum. Se estiver no comum, migre para o Business no aparelho antes.
2. O celular com esse número precisa estar em mãos: a autorização acontece nele, não no computador.
3. A pessoa que faz o Embedded Signup precisa ter acesso ao portfólio empresarial da Meta do negócio.
4. Decida antes se o histórico de conversas será compartilhado. É a pergunta do passo 6, e a resposta não pode ser mudada depois.

Vale reservar dez minutos sem interrupção. A conexão em si é rápida, mas há um QR code que expira e uma janela de 24 horas que começa a contar assim que o Embedded Signup termina.

Parte 1 — no computador: o Embedded Signup

1. Escolher o modo

No painel, em Conectar número, aparecem dois cartões: Dedicado (Cloud API) e Coexistência. O dedicado leva o número inteiro para a Cloud API e desliga o aplicativo naquele aparelho; a coexistência mantém os dois.

Escolha Coexistência. Os dois cartões abrem o mesmo Embedded Signup da Meta, mas com configurações diferentes por baixo — não dá para trocar de modo no meio do caminho.

2. Autorizar na janela da Meta

Abre uma janela do Facebook pedindo para selecionar os ativos de negócios. São dois campos:

• Portfólio empresarial — o portfólio da Meta do seu negócio. Se houver mais de um, escolha o que já detém a presença da marca.
• Conta do WhatsApp Business — aqui é onde a coexistência se distingue: a opção é Conectar um app do WhatsApp Business, e não criar uma conta nova. É ela que diz à Meta que o número continua vivendo no aplicativo.

Se a janela não abrir, o problema quase sempre é bloqueador de anúncios ou bloqueio de pop-up: o fluxo depende do SDK do Facebook e de uma janela separada. Libere o domínio e clique de novo.

3. O que acontece enquanto você espera

Quando a janela fecha, o painel recebe duas coisas que precisam chegar juntas:

• Um código de autorização, devolvido pelo login do Facebook.
• Os identificadores da conta e do número — o wabaId e o phoneNumberId —, que chegam por uma mensagem separada da janela da Meta.

Só com as duas o painel considera o passo concluído. A partir daí o servidor troca o código pelo token do cliente — essa troca nunca acontece no navegador — e assina o aplicativo aos webhooks da conta.

Uma diferença importante do modo dedicado: em coexistência o número NÃO é registrado na Cloud API. Registrá-lo é justamente o que tiraria o aplicativo do ar, e é por isso que esse passo é pulado.

Parte 2 — no celular: a autorização

Terminado o Embedded Signup, a Meta envia uma mensagem para o próprio número, no WhatsApp. É por ela que a segunda metade começa — e é a parte que ninguém antecipa, porque nada no computador avisa que ela existe.

4. A mensagem da Meta

Chega uma conversa do contato "Facebook Business", verificado, com um cartão: "Connect to the Business Platform — Continue the process of sharing your WhatsApp contacts and chats to the Platform", e um botão Connect.

Na mesma conversa aparece o aviso que passará a acompanhar os atendimentos: "Esta empresa usa um serviço seguro da Meta para gerenciar esta conversa".

5. A tela que explica o que muda

Tocar em Connect abre a tela "Conectar-se à Plataforma do WhatsApp Business", com três informações que vale ler antes de seguir:

• O aplicativo WhatsApp Business continua funcionando junto com a Plataforma.
• É possível compartilhar até seis meses do histórico de conversas — e históricos de grupos não podem ser compartilhados.
• A partir da conexão, todas as conversas individuais passam a ser gerenciadas por um serviço seguro da Meta, e um aviso disso aparece nas conversas.

6. A decisão sobre o histórico

Aparece um diálogo com duas opções e nenhuma terceira chance:

• Compartilhar todas as conversas — as conversas anteriores passam a existir também na plataforma, e a equipe continua os atendimentos em andamento.
• Não compartilhar conversas — a plataforma começa vazia, e será necessário iniciar conversas novas com os clientes.

Escolha com atenção. Se a pessoa recusar, não há como pedir de novo: reabrir essa decisão exige refazer o onboarding inteiro. E o pedido não dá erro quando é recusado — simplesmente nunca chega nada.

7. O QR code

A tela seguinte pede para apontar a câmera do celular para a tela do computador e ler o QR code que a janela da Meta exibe. É a etapa que amarra as duas metades: sem ela, o Embedded Signup fica pela metade.

Depois da leitura aparece "Conectando sua conta. Esse processo pode levar até 45 segundos". O aparelho pode pedir autenticação — Face ID, digital ou senha — antes de concluir; é uma exigência do sistema do celular, não da Meta.

8. A confirmação

No fim, o aplicativo mostra "Sua conta está conectada à [nome da plataforma]" e uma notificação avisando que o histórico está sendo compartilhado. A tela final, "Plataforma conectada", lista a conta da Meta e a conta do WhatsApp vinculadas, e é onde se desconecta.

Depois de conectado: quatro conferências

1. Abra uma conversa qualquer e confirme o aviso "Esta empresa agora usa um serviço seguro da Meta para gerenciar esta conversa". Ele aparecendo significa que a conexão está de pé do lado do cliente.
2. Peça a alguém para escrever ao número e responda pela API. A resposta sair confirma que a janela de 24 horas é compartilhada entre o aplicativo e a API — as duas conversam com o mesmo cliente.
3. Confira no painel que o número aparece conectado e em modo coexistência.
4. Anote onde se gerencia a conexão no celular: Configurações, Conta, Plataforma comercial.

Uma regra que só aparece na última tela e derruba conexões meses depois: abra o aplicativo pelo menos uma vez a cada 14 dias. Ficar mais do que isso sem abrir faz a conexão cair.

Vale saber também que uma conta do WhatsApp só pode estar conectada a uma plataforma comercial por vez. Conectar a outra desconecta esta.

O histórico: 24 horas e uma tentativa

Se o cliente autorizou o compartilhamento, os dados não vêm sozinhos: é preciso disparar a sincronização. E esse é o passo que menos perdoa erro.

• O prazo — 24 horas contadas do Embedded Signup.
• As tentativas — uma, por tipo de sincronização. Não há repetição.
• O que vem — até seis meses de conversas individuais e a lista de contatos do aparelho. Grupos não vêm.

Antes de disparar, assine os eventos no seu endpoint de webhook. Sem isso os dados são enviados e descartados.

Os eventos são messages, history e smb_app_state_sync. Os dois disparos ficam em Sincronizar histórico, na documentação.

O histórico chega em muitos webhooks, em blocos, de forma assíncrona. Um único webhook pode carregar milhares de mensagens: responda 2xx na hora e processe em segundo plano.

O que muda no dia a dia

• As mensagens digitadas no celular chegam até você — no evento smb_message_echoes, no mesmo formato das recebidas. Sem assinar esse evento, seu histórico fica com buracos: você vê o que o cliente escreve e o que a API envia, mas não o que a equipe respondeu pelo aparelho.
• Mudanças de contato viram evento — adicionar, renomear ou remover um contato no celular gera smb_app_state_sync, e isso continua acontecendo indefinidamente.
• Grupos seguem só no aplicativo — a API não os enxerga e mensagens de grupo não geram webhook.
• Chamadas seguem só no aplicativo — voz e vídeo não são expostas pela API.
• A qualidade do número é uma só — um envio mal recebido pela API derruba a qualidade que o atendimento humano também usa.

Quando dá errado

• A janela da Meta não abre — bloqueador de anúncios ou de pop-up. É a causa mais comum.
• A janela fecha e nada acontece — o fluxo foi interrompido antes do fim. Refaça: só com o código e os identificadores juntos a conexão é concluída.
• A mensagem da Meta não chega no celular — confirme que o número usado no Embedded Signup é o mesmo que está no aplicativo.
• O QR code expirou — recomece a leitura pelo aplicativo; o código é gerado de novo.
• O histórico não chegou — ou o cliente recusou o compartilhamento, ou os eventos não estavam assinados, ou as 24 horas passaram. O disparo não acusa nenhum dos três: simplesmente não chega webhook.

Voltando atrás

Desconectar o número no painel devolve a operação inteira para o aplicativo, e o histórico que estava no celular nunca saiu de lá. Pelo celular, o caminho é Configurações, Conta, Plataforma comercial.

Sair da coexistência para o modo dedicado é outra história: exige refazer o onboarding e desliga o aplicativo naquele aparelho.

Perguntas frequentes

Preciso do celular em mãos para conectar?

Precisa. A segunda metade do processo acontece no aplicativo WhatsApp Business, e sem ela a conexão não se completa.

O número fica fora do ar durante a conexão?

Não. Diferente do modo dedicado, em coexistência o número não é registrado na Cloud API — é justamente esse passo pulado que mantém o aplicativo funcionando.

Posso decidir depois se compartilho o histórico?

Não. A escolha acontece uma vez, no celular, e mudá-la exige refazer o onboarding inteiro.

O que acontece se eu não abrir o aplicativo por muito tempo?

A conexão cai. O aplicativo precisa ser aberto pelo menos uma vez a cada 14 dias.

Dá para conectar o mesmo número em duas plataformas?

Não. Uma conta do WhatsApp só pode estar conectada a uma plataforma comercial por vez; conectar a outra desconecta a atual.