Coexistência no WhatsApp: o app Business e a Cloud API no mesmo número

O que é a coexistência, e por que ela importa para quem já atende pelo app

A página Onboarding WhatsApp Business app users, da documentação da Cloud API, descreve um fluxo em que uma empresa que já usa o app WhatsApp Business conecta o mesmo número à plataforma da Meta, por meio de um parceiro, e passa a usar os dois ao mesmo tempo. A própria página registra que o recurso é chamado, às vezes, de “Coexistence” nos canais de suporte e na documentação de parceiros. Ele saiu em 11 de fevereiro de 2025, segundo o changelog.

Para a pequena e a média empresa brasileira, é a resposta à dúvida que mais aparece quando se fala em API: preciso abrir mão do app? Com a coexistência, não. O dono continua respondendo pelo celular, com as etiquetas, o catálogo e as respostas rápidas de sempre, e a mesma conversa passa a existir num inbox com vários atendentes, em automações, campanhas com template e integrações com o resto do sistema.

A alternativa é a migração completa, e a Meta é clara sobre o custo dela. Para levar um número do app para a Cloud API sem coexistência, é preciso apagar a conta do app, e, segundo a página que descreve essa migração, o histórico existente se perde e o número não volta a ser usado no app enquanto não for desregistrado da Cloud API. Na coexistência, o histórico é preservado. É por isso que, para quem tem anos de conversa no celular, a coexistência costuma ser o primeiro passo — e às vezes o único.

Sobre disponibilidade, uma ressalva honesta: a página atual não publica lista de países. A lista de exclusão que existia em 2025 não incluía o Brasil, e o changelog registra a liberação gradual de outros mercados — Índia, Austrália, Japão, União Europeia, Reino Unido e, em 2026, Nigéria e África do Sul. O erro 3441042, de recurso indisponível para números da região, continua existindo, o que indica que alguma restrição geográfica ainda vale em algum lugar.

Requisitos e o caminho do onboarding

Os requisitos oficiais são poucos. O app WhatsApp Business precisa estar na versão 2.24.17 ou mais nova. A conexão é feita por um parceiro da Meta — Solution Partner ou Tech Provider — pelo Embedded Signup, o fluxo de cadastro embutido no site do parceiro. Na configuração documentada, o parceiro passa whatsapp_business_app_onboarding como featureType; nas versões mais recentes do fluxo, a Meta também desvia para a coexistência automaticamente quando percebe que o número digitado já está no app.

Para o dono, o caminho é curto: ele informa o número, recebe no próprio app uma mensagem da conta oficial do Facebook Business, toca para conectar, escolhe se quer compartilhar o histórico de conversas e confirma — numa variante do fluxo, escaneando um QR code de dentro do app. O registro do número na Cloud API, que no onboarding comum é uma etapa à parte, é pulado: o número já está registrado. No fim, o parceiro recebe o evento FINISH_WHATSAPP_BUSINESS_APP_ONBOARDING e pode conferir os campos is_on_biz_app e platform_type do número.

Os erros do caminho dizem mais do que a lista de requisitos. O 3441045, com a mensagem de que é preciso mais atividade no app, aparece em número novo ou pouco usado — a Meta não publica quantos dias de uso bastam. O 2655093 avisa que trocar de parceiro não é suportado nesse fluxo e manda desconectar o parceiro atual pelo próprio app. E, depois de uma desconexão, a página de erros pede 15 minutos de espera antes de tentar de novo.

As 24 horas que não voltam: contatos e histórico

Terminado o onboarding, começa o relógio que mais importa. Segundo a página da coexistência, o parceiro tem 24 horas para sincronizar os contatos e o histórico de conversas do cliente; passado o prazo, o cliente precisa ser desconectado e refazer o fluxo inteiro. E a sincronização só pode ser feita uma vez — para repetir, o mesmo caminho: desconectar e começar de novo.

O pedido é feito por POST /<PHONE_NUMBER_ID>/smb_app_data, com sync_type igual a smb_app_state_sync para os contatos ou history para as conversas. A resposta é só o aceite do pedido, com um request_id; os dados chegam depois, pelos webhooks. Na nossa implementação, a ordem é contatos primeiro e histórico depois, para que as conversas encontrem a quem se ligar quando chegarem. A Meta pede que o dono mantenha o app aberto durante a sincronização, que pode levar vários minutos.

O que vem tem limites claros. Conversas individuais dos últimos seis meses — 180 dias contados do onboarding. Grupos não são sincronizados. Mídia só vem com arquivo quando foi enviada nos 14 dias anteriores ao onboarding; o resto chega como marcador, sem forma de buscar depois. Contatos vêm todos os que têm número de WhatsApp. Se o dono recusou compartilhar o histórico, o webhook history chega com o erro 2593109, e não há o que importar.

Por ser uma chance só, a sincronização não admite falha silenciosa. O nosso parser foi escrito a partir da documentação, e o pior desfecho possível seria receber o histórico, não reconhecer o formato, extrair zero mensagens e confirmar o webhook como se não houvesse nada — os seis meses sumiriam sem aviso, e o pedido não se repete. Por isso, quando chega histórico e nada é extraído, registramos a forma do payload, só chaves e contagens, sem telefone, nome ou corpo de mensagem. É o que permite consertar o parser sem precisar de um segundo cliente para reproduzir.

Histórico não é conversa nova

O webhook history entrega as conversas em pedaços. Cada um traz metadata.phase — 0 para o primeiro dia, 1 para até 90 dias, 2 para até 180 —, um chunk_order e um progress, que chega a 100 no fim. Dentro, vêm as conversas em threads[], cada mensagem com id, timestamp, tipo e um history_context.status. A Meta avisa que um único webhook pode descrever milhares de mensagens e recomenda guardar o conteúdo primeiro e processar depois, de forma assíncrona.

Os pedaços chegam fora de ordem, e a Meta reentrega. A consequência de engenharia é que nada pode depender de sequência: a idempotência de verdade é o wamid de cada mensagem batendo num índice único, e o fim do processo é o progress: 100, não a chegada do último chunk_order. Mensagem sem wamid ou sem horário utilizável deve ser descartada — e contada, para o log não dizer que importou tudo.

A lição mais importante, porém, é de produto: histórico não pode passar pelo mesmo caminho das mensagens que chegam ao vivo. Se passar, cada conversa de meses atrás abre uma janela de atendimento de 24 horas com o relógio errado, dispara os prazos de atendimento, aciona a IA, a resposta automática, a notificação no celular e os webhooks do cliente. E há um efeito pior, menos óbvio: um “SAIR” que o cliente mandou há quatro meses, reprocessado como mensagem nova, marca o contato como descadastrado e bloqueia campanhas para alguém que nunca pediu isso agora.

Na nossa implementação, o histórico é gravação, não conversa: vai direto para o armazenamento, com o instante real de cada mensagem, sem abrir janela e sem acionar nada. A mídia que não veio vira um marcador explícito — foto indisponível, áudio indisponível — em vez de uma bolha de imagem quebrada, que pareceria defeito do sistema quando o atendente clicasse.

Telefone sem “+” e o nono dígito

A Meta manda o telefone do cliente sem o “+”, no formato wa_id — 5511… em vez de +5511…. É o mesmo formato dos webhooks de sempre, mas o histórico tem uma particularidade que pesa no Brasil: ele traz conversas antigas, e conversas antigas trazem números gravados de jeitos diferentes. O mesmo cliente pode aparecer no histórico com e sem o nono dígito do celular, e no seu cadastro de uma terceira forma.

Sem casar as grafias, seis meses de histórico viram contatos e conversas duplicados em escala: a mesma pessoa partida em duas fichas, cada uma com metade da conversa. Na nossa implementação, o histórico passa pelo mesmo casamento de telefone que o inbox usa — com e sem o nono dígito — antes de decidir a qual contato cada conversa pertence.

E a decisão padrão precisa ser juntar, não pular. Num número que já atendia pelo app e acabou de entrar na API, o normal é já existir conversa viva para boa parte dos telefones do histórico: o cliente escreveu ontem, a mensagem já chegou pelo webhook comum. O histórico deve ser mesclado nessa conversa, ordenado pelo horário real, e não descartado por “já existir” — nem gravado como uma segunda thread.

Os contatos pedem uma regra parecida. O webhook smb_app_state_sync traz a agenda do aparelho, com action de add ou remove. Uma recomendação nossa: use as adições para preencher nome, e ignore as remoções. Apagar um contato do sistema porque ele sumiu da agenda do celular do dono destruiria histórico de atendimento por causa de um evento que não fala sobre isso.

O dono responde pelo celular: os ecos

A coexistência não é só o onboarding. Depois dele, o dono continua respondendo pelo app, e cada mensagem que ele manda de lá chega ao parceiro pelo webhook smb_message_echoes, com remetente, destinatário, id, horário e tipo. Segundo a referência, o eco também chega quando o dono edita ou apaga uma mensagem no app. É contínuo, e é o que mantém a conversa inteira dos dois lados.

Sem ingerir os ecos, o atendente que usa o inbox vê a pergunta do cliente e nenhuma resposta, e responde de novo. O cliente recebe a mesma informação duas vezes, de duas pessoas, às vezes com respostas diferentes. Todo eco é mensagem de saída — é a empresa falando — e entra na conversa com o horário em que foi enviado, como se tivesse saído do próprio inbox.

Uma regra de janela que confunde: mensagens enviadas pelo app não criam, não estendem e não afetam a janela de atendimento da Cloud API, diz a página da coexistência. A janela só abre quando o cliente escreve depois do onboarding. Para quem escreveu pouco antes da conexão, a empresa só consegue responder pela API com template. O dono pode ter acabado de conversar com o cliente pelo celular, e mesmo assim o inbox precisa de um template para falar com ele.

E há os aparelhos vinculados. A empresa pode manter até quatro dispositivos acompanhantes, mas no onboarding todos são desvinculados, e o dono precisa vincular de novo os que usa. Todos são suportados, exceto o WhatsApp para Windows e o WhatsApp para WearOS — e mensagens enviadas a partir de um acompanhante não suportado não disparam webhook. Na prática, o que o funcionário responde pelo aplicativo de Windows não aparece no sistema. Vale avisar o cliente antes de conectar.

O que muda no app depois da conexão

Algumas funções do app são desligadas nas conversas individuais quando o número entra em coexistência: mensagens temporárias, visualização única e localização em tempo real. As listas de transmissão também: não dá para criar novas, e as existentes ficam só para leitura. Para a pequena empresa que faz divulgação por lista de transmissão, essa é a mudança que mais pesa — a divulgação passa a ser feita por template, pela API, com as regras e o custo de template.

Outras funções continuam no app, mas não existem na API: grupos, chamadas de voz e vídeo, catálogo, pedidos, status, mensagens de saudação e de ausência, respostas rápidas e etiquetas. O dono continua usando tudo isso no celular; o inbox não enxerga. A comparação da página é útil para alinhar expectativa: a coexistência soma a API ao app, não transforma o app em API.

E alguns recursos da plataforma ficam fora do alcance de números do app. A documentação de grupos diz que eles não estão disponíveis para números do app WhatsApp Business. A API de chamadas exige que o número esteja em uso com a Cloud API e não com o app. E a Meta não concede o selo de conta comercial oficial a números do app. Quem planeja usar algum desses recursos precisa, em algum momento, da migração completa.

Vazão, cobrança e o limite que vale

A vazão de um número em coexistência é fixa. Segundo a página Throughput, números usados ao mesmo tempo no app e na Cloud API têm “a fixed throughput of 20 mps” — 20 mensagens por segundo, contando entrada e saída, de todos os tipos. Para comparação, um número só na Cloud API começa em 80 e pode subir automaticamente até 1.000. Passar do teto devolve o erro 130429, como em qualquer número.

Para a operação típica de pequena e média empresa, 20 por segundo sobra: são 1.200 mensagens por minuto. O teto aparece em campanha grande, e aí ele vira planejamento — uma lista de 50 mil contatos leva bem mais que alguns minutos para sair, e o atendimento ao vivo divide a mesma vazão com o disparo. O limite de mensagens por portfólio, que conta destinatários únicos fora da janela em 24 horas, vale normalmente.

A cobrança separa as duas pontas. A página da coexistência diz que as mensagens enviadas pelo app continuam gratuitas, e as enviadas pela Cloud API seguem o preço da Cloud API. Desde 1º de outubro de 2026, isso inclui atendimento: cada número tem 1.000 mensagens de atendimento grátis por mês, e a partir da 1.001ª a Meta cobra. Utility e marketing são cobrados por mensagem entregue, com a janela aberta ou fechada.

A leitura prática, que é nossa e não uma regra da Meta: responder pelo app não custa nada; responder pelo inbox consome a franquia mensal de atendimento do número e, depois dela, custa; e disparo ativo, com template, só existe pela API. Isso ajuda a decidir quem atende por onde — e explica por que algumas empresas deixam o dono no app e a equipe no inbox.

Manter conectado, desconectar e trocar de parceiro

A integração depende do celular. O webhook account_update traz o motivo quando a conexão cai, e dois deles são de inatividade: PRIMARY_INACTIVITY, quando o aparelho principal fica cerca de 14 dias sem uso, e COMPANION_INACTIVITY, cerca de 30 dias. A Central de Ajuda do WhatsApp diz a mesma coisa sobre aparelhos vinculados em geral. Para o dono, a regra é simples: o celular com o app precisa continuar em uso.

Trocar de aparelho, reinstalar o app ou registrar o número de novo desconecta a Cloud API automaticamente, com o evento ACCOUNT_OFFBOARDED. No novo registro, o dono vê uma opção já marcada para reconectar, e o processo costuma levar poucos minutos, terminando com ACCOUNT_RECONNECTED. Durante a reconexão, o envio pela API fica suspenso. Quem assina account_update sabe disso na hora; quem não assina descobre pelas mensagens que não saíram.

Desconectar de propósito é feito pelo app, não pela API. A página da coexistência diz que a API de desregistro não funciona para número em uso no app e na Cloud API; o caminho é o próprio dono, nas configurações da conta, na área da plataforma comercial. O parceiro recebe PARTNER_REMOVED, com um disconnection_info que diz o motivo e quem iniciou.

Por fim, o novo modelo de contas da Meta, que entrou em vigor em 23 de setembro de 2026, trata a coexistência como exceção. No onboarding, a Meta converte a conta existente numa conta de mensagens compatível e não cria a conta de mensagens própria de cada parceiro, como faz no fluxo comum. O fluxo também não aceita troca de parceiro — o erro 2655093 manda desconectar o atual primeiro —, e as conversas com vários parceiros não suportam números do app. Na prática, um número em coexistência trabalha com um parceiro de cada vez.