Coexistência WhatsApp Business + API: guia definitivo

Coexistência é o recurso da Meta que deixa um mesmo número funcionar ao mesmo tempo no aplicativo WhatsApp Business do celular e na API oficial do WhatsApp. O app continua instalado, com as conversas de sempre, e um sistema passa a receber e enviar mensagens por aquele número. Você não precisa de chip novo, não perde o número e pode trazer até 6 meses de histórico para a plataforma. Em troca, aceita algumas limitações que a Meta impõe a esse modo, e a principal é o ritmo de 20 mensagens por segundo.

Este guia explica o que a coexistência é, o que muda no dia a dia, o que a Meta exige, o que ela tira do app e como ativar em minutos.

O que é coexistência, em resposta curta

Na documentação para desenvolvedores, a Meta chama o recurso de "Onboard WhatsApp Business app users": conectar à API um número que já está em uso no aplicativo WhatsApp Business. No material comercial e entre parceiros, o nome é "WhatsApp Coexistence", ou coexistência. É a mesma coisa.

A API oficial do WhatsApp é a Cloud API, a porta que a Meta abre para que sistemas enviem e recebam mensagens por um número de empresa. Até pouco tempo, usar essa porta significava abrir mão do aplicativo. A coexistência derruba essa escolha: o número passa a ter duas pontas, o app e a API, e as duas veem as mesmas conversas.

Para quem tem uma loja, uma clínica, uma escola ou vende curso online, a diferença é prática. O número que os clientes já conhecem continua no celular da equipe e, ao mesmo tempo, ganha o que o app sozinho não dá: envio em massa com mensagens aprovadas pela Meta, integração com o sistema da empresa e resposta automática a quem escreve.

Como era antes: número exclusivo da API, sem app no celular

Antes da coexistência, um número só podia estar em um lugar: registrado no app WhatsApp Business ou registrado na Cloud API. Conectar à API exigia tirar o número do aplicativo, e a partir daí ele só respondia por software.

Isso criava três problemas para o negócio pequeno. O histórico ficava no celular, e a plataforma começava do zero. A equipe que atendia pelo celular precisava passar a atender por um painel, e muitos desistiam da API por isso ou compravam um chip novo só para ela, operando dois números. E a migração era irreversível no momento em que acontecia: se algo desse errado no meio, o número ficava fora do ar nas duas pontas.

A coexistência elimina os três de uma vez. O número não se move. Ele ganha uma segunda ponta.

O que a coexistência muda

O app continua no celular, com as conversas de sempre

Depois de conectar, o aplicativo WhatsApp Business continua instalado no mesmo aparelho, logado no mesmo número, com as mesmas conversas e os mesmos contatos. A equipe que atende pelo celular não precisa mudar de hábito. A única diferença visível dentro do app é uma tela nova em Configurações, chamada Plataforma comercial, que mostra o parceiro conectado e permite desconectar. Fora isso, o app funciona como antes, exceto pelos recursos que a Meta desliga nesse modo, listados mais adiante.

A API recebe e envia pelo mesmo número

A partir da conexão, toda mensagem que chega para o número é entregue ao app e à API ao mesmo tempo. Para o cliente que escreve, nada muda. Do lado do sistema, o número passa a responder por dois caminhos:

• Envio pela API: o sistema manda uma mensagem, ela sai pelo seu número e aparece na conversa do app também. Quem está com o celular na mão vê a mensagem enviada pelo sistema como se fosse dele.
• Eco do app: quando alguém da equipe responde pelo celular, a Meta avisa a API por um evento chamado smb_message_echoes, o "eco" da mensagem enviada pelo app. É o que permite ao painel mostrar a conversa inteira, com o que saiu pela API e o que saiu pelo celular.

No Frame Conexa, o painel monta a conversa a partir das duas fontes: uma mensagem enviada pelo celular às 9h e uma resposta do sistema às 9h05 aparecem na mesma linha do tempo. Quem consome a API recebe o eco pelo webhook de saída, no mesmo formato dos outros eventos:

{
  "type": "smb_message_echoes",
  "clientId": "8",
  "instanceId": "6ed76b84-4d65-4f3d-88c1-8d4174bdce73",
  "customerId": null,
  "customerRef": null,
  "payload": {}
}

Nota: segundo a Meta, as mensagens enviadas pelo app continuam grátis e não abrem, não estendem nem afetam as janelas da API. Quem abre a janela de 24 horas é o cliente, quando escreve. Por isso, a resposta dada pelo celular a quem chegou por anúncio não abre a janela grátis de 72 horas: para ter essa janela, a primeira resposta precisa sair pela API.

A regra de envio é a mesma de qualquer número na Cloud API: mensagem livre só dentro da janela de 24 horas aberta pelo cliente; fora dela, só mensagem aprovada pela Meta, chamada de template. A coexistência não relaxa essa regra. O app do celular continua podendo escrever a qualquer momento, porque a regra da janela vale para a API, não para o aplicativo.

Quais são os requisitos oficiais da Meta?

A Meta publica os requisitos na página de onboarding de usuários do app WhatsApp Business. São poucos, mas dois deles costumam derrubar tentativas.

Sobre o parceiro: a Meta só libera a coexistência para quem passou pelo App Review dela com as permissões de gerenciamento e envio, e implementou os webhooks obrigatórios desse modo. O Frame Conexa é Tech Provider verificado, e o fluxo de conexão é o Embedded Signup da própria Meta, aberto dentro do painel. A senha do WhatsApp nunca passa pelo parceiro; o que ele recebe é uma autorização.

Versão do app, celular ativo e o que acontece após 14 dias sem abrir

A versão do app é o requisito mais simples de checar e o mais fácil de esquecer. Atualize o WhatsApp Business na loja do celular antes de começar.

O celular ativo é o requisito que surpreende depois. Na coexistência, o aparelho principal continua sendo a raiz do número. Se ele ficar inativo por cerca de 14 dias, a Meta desconecta a integração por um evento chamado PRIMARY_INACTIVITY, e o número volta a viver só no app. Nada é perdido no celular, mas a API para de receber e enviar até uma nova conexão. Um chip guardado numa gaveta não serve: o celular precisa ficar ligado, com internet, e o app precisa ser aberto de vez em quando. Se a intenção é ter um número que ninguém opera pelo celular, o caminho é o número novo só na API, tratado no fim deste guia.

Atenção: trocar o número de aparelho e registrá-lo de novo no app também desfaz a coexistência. A Meta avisa o parceiro por um evento de desligamento, e o painel do Frame Conexa marca o número como desconectado. Reconectar é refazer o fluxo, e o histórico só é importado durante a conexão. O artigo sobre coexistência desconectada lista os seis motivos que a Meta informa e o passo a passo para voltar.

Histórico e contatos: os 6 meses que a Meta compartilha

Este é o motivo pelo qual a coexistência vale mais do que parece. No momento da conexão, o dono do número decide se quer compartilhar o histórico com o parceiro. Se aceitar, a Meta envia para a plataforma todas as mensagens enviadas e recebidas nos 180 dias anteriores, os "6 meses" do material comercial.

Contatos também entram. A Meta sincroniza todos os contatos que têm WhatsApp por um evento separado, chamado smb_app_state_sync. É assim que o painel já nasce com nome e número de quem você conversa, sem digitar nada.

Duas regras importantes sobre o que chega:

• Texto vem inteiro dentro dos 180 dias. Imagens, áudios e documentos só vêm para mensagens dos últimos 14 dias. Mensagem mais antiga chega com o texto e sem a mídia.
• O histórico é importado uma vez, na conexão. Não existe um botão "importar de novo" mais tarde. Quem recusa o compartilhamento na hora e muda de ideia depois precisa desconectar e refazer o fluxo.

No painel do Frame Conexa, essas mensagens aparecem na conversa como histórico, marcadas de forma diferente das mensagens novas. Elas dão contexto a quem atende, mas não reabrem janelas de envio: uma conversa antiga importada não conta como "o cliente escreveu agora".

As três fases da importação e a janela de 24 horas para sincronizar

A Meta entrega o histórico em três fases, por um evento chamado history: primeiro as mensagens do último dia, depois as do dia 1 ao dia 90, depois as do dia 90 ao dia 180. As mais recentes chegam primeiro para o painel ficar útil logo.

O parceiro tem 24 horas, contadas da conexão, para concluir a sincronização. Se não conseguir, a Meta espera que o número seja desligado. É por isso que a orientação de manter o app aberto durante a importação existe: o celular participa do envio dos dados, e um app fechado atrasa as fases.

No Frame Conexa, o passo Sincronizar mostra o andamento das duas sincronizações, de conversas e de contatos, e guarda a porcentagem recebida até a Meta reportar 100%. Se a importação estagnou, a saída é abrir o WhatsApp Business no celular e esperar. Não há como forçar pelo painel, porque quem envia os dados é o aparelho.

Quais limitações você precisa aceitar?

Aqui está a parte que a maioria dos textos sobre coexistência esconde. A Meta desliga alguns recursos no app quando o número está conectado à API, e deixa outros de fora da API. Nenhuma dessas restrições é do provedor. São todas da Meta, e valem para qualquer parceiro.

20 mensagens por segundo e sem listas de transmissão novas

A limitação que mais pesa é o ritmo. Um número exclusivo da Cloud API envia 80 mensagens por segundo por padrão, e a Meta sobe isso automaticamente para números grandes. Um número em coexistência fica fixo em 20 mensagens por segundo, porque o app e a API precisam ficar sincronizados.

Para atendimento, 20 por segundo não faz diferença nenhuma. Para envio em massa, faz alguma: uma campanha de 5.000 mensagens leva pouco mais de quatro minutos no ritmo máximo, contra pouco mais de um minuto num número exclusivo. O Frame Conexa respeita esse teto por número e controla o ritmo de cada campanha sozinho. Na prática, o que limita o envio em massa não é o ritmo. É a capacidade do número definida pela Meta, o número de pessoas diferentes que o seu portfólio pode alcançar fora da janela em 24 horas, e isso vale igual nos dois modos.

Listas de transmissão são o segundo impacto. No app, não dá mais para criar listas, e as que já existiam ficam só de leitura: dá para ver, não dá para enviar por elas. Quem usava lista de transmissão para avisar clientes migra para o envio em massa pela API, com mensagens aprovadas pela Meta e consentimento de quem recebe. O guia de envio em massa pelo WhatsApp oficial explica esse caminho.

O que muda no app e o que fica fora da API

A tabela abaixo resume a comparação que a página oficial da Meta publica para números em coexistência. A primeira coluna diz o que acontece no aplicativo do celular; a segunda, se o recurso passa pela API.

Duas observações sobre essa lista. Grupos, chamadas e catálogo continuam no celular como antes, mas o sistema não os enxerga: uma venda fechada por ligação ou pelo catálogo do app não aparece no painel. E tudo o que fica fora da API continua sendo operado pelo app, como o perfil comercial, que num número em coexistência se edita pelo celular. O Frame Conexa não cobra por mensagem e não impõe limite de envio próprio; o que limita é a Meta, pela capacidade do número e pela qualidade.

Importante: a Meta muda a cobrança da API em 01/10/2026. Mensagens livres dentro da janela de 24 horas e mensagens de utilidade dentro da janela passam a ser cobradas por mensagem. O app WhatsApp Business do celular não é afetado, só a API. Em coexistência, isso significa que uma resposta enviada pelo celular continua sem custo, e uma resposta enviada pelo sistema passa a seguir a tabela publicada pela Meta. Confira o rate card oficial e o artigo sobre quanto custa a API do WhatsApp.

Como ativar em minutos com o Frame Conexa

A conexão acontece dentro do painel, em cinco passos: Escolher, Preparar, Autorizar, Sincronizar e Testar. A autorização em si é o Embedded Signup da Meta, numa janela dela.

1. Escolher. No painel, clique em Conectar WhatsApp e escolha "Número já em uso no WhatsApp". A outra opção é "Número novo, só na API".
2. Preparar. Atualize o WhatsApp Business no celular, confira que o aparelho principal está com internet e deixe o app aberto.
3. Autorizar. Uma janela da Meta abre. Nela você entra com a conta que administra a empresa, escolhe ou cria o portfólio de negócios, escolhe a conta do WhatsApp Business e o número. No celular, o app pede confirmação e pergunta se você quer compartilhar histórico e contatos. Aceite, se quiser os 6 meses no painel. A janela tem prazo de 15 minutos; passado isso, a autorização morre e é preciso recomeçar.
4. Sincronizar. O painel recebe a autorização, confere que o número está de fato em coexistência, ativa os eventos e acompanha a importação de conversas e contatos.
5. Testar. Envie a primeira mensagem para o seu próprio celular pelo painel e confira que ela apareceu na conversa do app também.

Se quem tem o celular na mão é um cliente seu, como no caso de uma agência, gere no painel um link de conexão compartilhável. O cliente abre o link, sem login, e faz só a autorização. O número nasce na conta de quem gerou o link.

Depois da conexão, o número responde à API pública como qualquer outro. O primeiro envio por código é o mesmo do guia de início rápido:

curl -X POST https://frameconexa.com/api/v1/instances/$FRAME_CONEXA_INSTANCE_ID/messages \
  -H "Authorization: Bearer fc_SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to":"5585999990000","type":"text","text":{"body":"Olá!"}}'

Nada no envio, no webhook ou nas campanhas muda por causa do modo. A coexistência é uma decisão do momento da conexão; depois dela, o número é um número na Cloud API.

O erro 2388002: "parceiro já atribuído"

O erro mais comum nesse caminho aparece na janela da Meta, na etapa em que você informa o número: "Failed to check phone number eligibility", código 2388002. Nada chega ao parceiro, porque a autorização morre antes de ser emitida. De fora, parece que a pessoa desistiu.

A causa que medimos em produção, em agosto de 2026, foi um parceiro já atribuído: uma tentativa anterior do próprio fluxo tinha deixado o parceiro com acesso à conta do WhatsApp Business do número. Com o parceiro lá, a checagem de elegibilidade falha em toda tentativa seguinte.

O conserto é no Business Manager do dono do número: Configurações, Parceiros, o parceiro em questão, a conta do WhatsApp, Gerenciar, Remover acesso. Ao refazer o fluxo, a elegibilidade passa e o próprio Embedded Signup reatribui o parceiro.

Atenção: não remova o número da conta do WhatsApp Business nem apague a conta para "começar do zero". A elegibilidade para coexistência depende do histórico de atividade do número no app, e reiniciar esse vínculo zera o relógio; parceiros relatam esperas de semanas a meses. Desfazer o vínculo pelo botão de desconectar do app, ou remover o acesso do parceiro no Business Manager, não tem esse efeito.

Quando a tentativa cai antes de existir qualquer requisição, o painel do Frame Conexa registra a queda do lado do navegador, com o código do erro quando a Meta o informa. É assim que o suporte distingue "a Meta recusou" de "a pessoa fechou a janela".

Há também o caso em que a janela da Meta nem oferece a coexistência e abre o cadastro de número novo. As causas e as soluções estão em opção de coexistência não aparece.

Por que o número em coexistência nunca passa por /register

Um detalhe técnico explica por que a coexistência é segura e por que a direção contrária não é.

Na Cloud API, um número novo precisa ser registrado por uma chamada chamada /register, com um PIN de seis dígitos. É o que diz à Meta "este número agora é operado pela API". Um número em coexistência já está registrado, pelo app do celular. Chamar /register nele desloga o aplicativo, de forma irreversível daqui: o número vira exclusivo da API e o celular perde o WhatsApp Business.

Por isso o Frame Conexa nunca chama /register num número em coexistência. Se você escolher "Número novo" e a Meta devolver um número que na verdade está no app, o painel corrige a modalidade para coexistência e segue. O inverso nunca acontece: se você escolheu coexistência e a Meta informa que o número não está no app, o fluxo para e avisa, em vez de registrar por conta própria e derrubar o aplicativo do celular. Descer é reversível; subir não é. O sinal conferido é o campo is_on_biz_app do número, que a Meta devolve depois da autorização.

Coexistência ou número novo só na API? Como escolher

As duas modalidades existem no painel, e a pergunta certa é sobre quem vai operar o número.

Escolha coexistência quando o número já é conhecido pelos clientes, quando a equipe atende pelo celular e vai continuar atendendo, e quando o histórico importa. É o caso da maioria das lojas, clínicas e escolas, e é a única forma de migrar para a API oficial sem perder o número nem as conversas.

Escolha número novo quando ninguém vai operar pelo celular, quando o volume de envio justifica o ritmo maior, ou quando o número vai servir só a um sistema. Nesse modo o perfil comercial, com foto, descrição e endereço, é editado pelo painel, porque não há app.

Um caminho comum é ter os dois: o número principal em coexistência, para atender, e um número novo só na API, para envio em massa. O Frame Conexa vende por número, e cada um pode ser de atendimento ou de marketing. Os planos estão em preços.

Se o número já esteve bloqueado ou restrito pela Meta, resolva isso antes de conectar: um número com restrição ativa não ganha capacidade por entrar na API. O artigo sobre WhatsApp Business bloqueado explica o que fazer nesse caso.

Próximo passo

Se o seu número já está no WhatsApp Business e você quer a API oficial sem abrir mão dele, a coexistência é o caminho, e a conexão leva alguns minutos. Veja os planos por número e, para o lado técnico, o guia de início rápido mostra o primeiro envio pela API logo depois de conectar.