---
title: Coexistência WhatsApp Business + API: guia definitivo
description: Coexistência do WhatsApp: use o mesmo número no app WhatsApp Business e na API oficial da Meta. Requisitos, histórico de 6 meses, limitações e como ativar.
date: 2026-09-06
category: coexistencia
tags: coexistência, whatsapp business, api oficial, histórico de conversas, embedded signup
author: gabriel-miranda
cover: /blog-assets/covers/coexistencia-whatsapp-business-api.jpg
coverAlt: Equipe usando notebook e smartphone no escritório
coverSource: https://www.pexels.com/photo/4968560/
---

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](/blog/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:

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

> **Nota:** o eco informa que a mensagem saiu pelo app, mas não traz confirmação de cobrança para o provedor. Uma resposta enviada pelo celular dentro da janela de anúncio de 72 horas, por exemplo, abre a janela grátis segundo a regra documentada pela Meta, e o painel a aplica de boa-fé, sem ter como confirmar pelo recibo de cobrança, porque esse recibo não chega para mensagens enviadas pelo app.

A regra de envio é a mesma de qualquer número na Cloud API: mensagem livre só dentro da [janela de 24 horas](/blog/janela-de-24-horas-whatsapp) 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.

| Requisito | De quem é a regra | O que acontece se falhar |
|---|---|---|
| App WhatsApp Business versão 2.24.17 ou superior | Meta | O fluxo recusa o número na etapa de elegibilidade |
| Número ativo no app, no aparelho principal | Meta | Sem app ativo não há o que coexistir |
| Parceiro Tech Provider ou Solution Partner, com Cloud API, webhooks e Embedded Signup aprovados | Meta | Só um parceiro nessa condição consegue oferecer o recurso |
| Aparelho principal ativo, com o app aberto de tempos em tempos | Meta | Cerca de 14 dias sem atividade desconectam a integração |
| Manter o app aberto durante a importação do histórico | Meta, como orientação | Importação pode ficar incompleta |

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](/blog/embedded-signup-whatsapp) 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.

## 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 ou restringe uma lista de recursos no app quando o número está conectado à API. Nenhuma dessas restrições é do provedor. São todas da Meta, e valem para qualquer parceiro.

### 20 mensagens por segundo, sem grupos, sem listas de transmissão no app

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 ainda deixa você escolher um ritmo mais lento por campanha. Na prática, o que limita o envio em massa não é o ritmo. É a [capacidade do número](/blog/limite-de-mensagens-whatsapp-business-api) 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.

Grupos e listas de transmissão são o segundo impacto. No app, grupos deixam de funcionar para o número conectado. Listas de transmissão 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](/blog/disparo-em-massa-whatsapp-oficial) explica esse caminho.

### O que fica só de leitura e o que é desativado

A tabela abaixo resume o que a página oficial da Meta lista para o app quando o número está em coexistência.

| Recurso do app | Situação na coexistência |
|---|---|
| Conversas individuais, enviar e receber | Funciona |
| Grupos | Não suportado |
| Listas de transmissão existentes | Somente leitura |
| Mensagens temporárias | Não suportado |
| Visualização única | Não suportado |
| Localização em tempo real | Não suportado |
| Chamadas de voz e vídeo | Não suportado |
| Catálogo e pedidos | Não suportado |
| Ferramentas de mensagens de marketing do app | Não suportado |

Duas observações sobre essa lista. Se o seu atendimento depende de ligação pelo WhatsApp ou de catálogo dentro do app, teste a coexistência num número secundário antes de conectar o principal. E as "ferramentas de mensagens de marketing" do app são os recursos de envio promocional do próprio aplicativo: na coexistência, esse papel passa para a API, com mensagens de marketing aprovadas pela Meta. 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](/blog/whatsapp-business-api-preco).

## 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](/docs/quickstart):

```bash
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".

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

| Critério | Coexistência | Número novo só na API |
|---|---|---|
| App no celular | Continua, com as conversas | Não existe |
| Número | O que você já usa | Um chip novo, registrado na API |
| Histórico | Até 180 dias importados | Começa do zero |
| Ritmo de envio | 20 mensagens por segundo | 80 por segundo, com upgrade automático |
| Grupos, chamadas, catálogo no app | Não suportados | Não se aplica |
| Depende do celular ligado | Sim, cerca de 14 dias sem atividade desconectam | Não |
| Perfil comercial | Editado pelo app | Editado pelo painel ou pela API |
| Quem atende | Equipe pelo celular e o sistema | Só o sistema ou um painel |

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](/#precos).

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](/blog/whatsapp-business-bloqueado-o-que-fazer) explica o que fazer nesse caso.

## Perguntas frequentes

### Coexistência do WhatsApp perde o histórico de conversas?

Não. O app do celular mantém tudo o que já tinha. E, se o dono do número aceitar o compartilhamento na hora da conexão, a Meta envia para a plataforma as mensagens dos 180 dias anteriores, em três fases, com mídia só dos últimos 14 dias. A importação acontece uma vez, durante a conexão; quem recusa e muda de ideia depois precisa desconectar e refazer o fluxo.

### Posso continuar usando o app WhatsApp Business no celular?

Sim. É o ponto central da coexistência. O app continua no mesmo aparelho, com as mesmas conversas, e a equipe pode responder por ele normalmente. O que sai pelo celular aparece no painel como eco, e o que o sistema manda pela API aparece na conversa do app. A regra da janela de 24 horas vale só para o que sai pela API.

### Quais funções o app perde na coexistência?

Segundo a página oficial da Meta: grupos, mensagens temporárias, visualização única e localização em tempo real deixam de funcionar; listas de transmissão que já existiam ficam somente leitura; chamadas de voz e vídeo, catálogo e pedidos e as ferramentas de marketing do app aparecem como não suportados. Conversas individuais continuam funcionando. Todas essas restrições são da Meta, e valem para qualquer parceiro.

### O que acontece se eu ficar dias sem abrir o app?

O aparelho principal precisa continuar ativo. Se ele ficar cerca de 14 dias sem atividade, a Meta desconecta a integração e o número volta a viver só no app. Nada some do celular, mas a API para de receber e enviar até você refazer a conexão. Manter o celular ligado, com internet, e abrir o app de vez em quando evita isso.

### Coexistência funciona para envio em massa?

Funciona, com o ritmo fixo de 20 mensagens por segundo que a Meta impõe a esse modo, contra 80 por segundo num número exclusivo da API. Para a maioria das campanhas isso é questão de minutos, não de viabilidade. O que de fato limita o alcance é a capacidade do número definida pela Meta, e ela vale igual nos dois modos. O envio precisa usar mensagens de marketing aprovadas pela Meta e consentimento de quem recebe.

## 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](/#precos) e, para o lado técnico, o [guia de início rápido](/docs/quickstart) mostra o primeiro envio pela API logo depois de conectar.