Um número.O aplicativo e a API, ao mesmo tempo.
Coexistence é o modo oficial da Meta para rodar o app do WhatsApp Business e a Cloud API em um único número ao mesmo tempo. A equipe continua atendendo pelo celular, com as mesmas conversas e o mesmo histórico, enquanto o software envia e recebe na mesma linha.
O easyCoexistence conecta o número pelo Embedded Signup da Meta, acompanha a conexão pelos webhooks da Meta e por verificações próprias, e manda por e-mail o motivo e a correção se a Meta derrubar o número.
A escolha que existia, e não existe mais
Coexistence não é uma API nova. É a remoção de uma bifurcação que impedia quase todo negócio pequeno de automatizar qualquer coisa.
A equipe atende pelo celular. Nada pode ser automatizado, integrado ou medido.
Sem APIO software alcança o número. O aplicativo Business para de funcionar nele e a equipe muda de ferramenta.
Sem appA Meta conecta a Cloud API a um número que o app do WhatsApp Business continua usando. As duas superfícies ficam ativas na mesma linha, e cada uma enxerga o que a outra envia.
Quem opera um número assim
Dois grupos, querendo coisas opostas do mesmo recurso, e é por isso que a conexão importa mais que qualquer painel em cima dela.
Uma equipe pequena, um número impresso numa van ou numa fachada, e noites respondendo as mesmas quatro perguntas. Não estão substituindo ninguém. Querem que confirmações, lembretes e a primeira resposta fora do horário aconteçam sem um humano, enquanto o celular continua servindo para todo o resto.
Muitos clientes, cada um com um número que ninguém pode migrar ou tocar. Precisam que esses números sejam alcançáveis pelos sistemas que constroem, e precisam adicionar o próximo sem uma reunião comercial. Coexistence é a única rota oficial para um número que a equipe do cliente ainda atende na mão.
Como um número passa a estar nos dois, e para onde vão os eventos de mensagem
Quatro etapas. A única que mexe no celular é escanear um código, e a que decide a sua arquitetura é a primeira.
Tenha o endpoint pronto antes de começar o onboarding
A Meta verifica um destino antes de entregar qualquer coisa a ele. Ela chama a sua URL com um GET contendo hub.mode=subscribe, o seu hub.verify_token e um hub.challenge, e o seu endpoint precisa devolver o hub.challenge exatamente como veio.
O destino precisa ser HTTPS, e o token de verificação é obrigatório. A gente valida os dois antes de a chamada ser feita, então uma URL malformada falha na nossa porta em vez de parecer conectada e não entregar nada.
Nada está conectado ainda. Isto decide onde as mensagens vão chegar. Provedor no caminhoArmazenado nos servidores deleA plataforma deleRecebe e armazena as mensagensVocêUma cópia, no tempo deleEasyCoexistenceSó configuraçãoSeu endpointAinda não verificadoNósDefinimos a rota, não estamos nelaRode o Embedded Signup da Meta e escaneie no app
A janela da própria Meta abre. Você escolhe o Portfólio de Negócios, a conta do WhatsApp Business e o número já registrado no app do WhatsApp Business, e depois aprova a conexão no celular escaneando um código.
É aqui também que você escolhe se compartilha o histórico de conversas existente. É uma decisão única do onboarding e não pode ser mudada depois. O app Business continua funcionando assim que o escaneamento termina.
A segunda superfície aparece. A primeira não é removida. Depois de uma migraçãoUma superfícieSó Cloud APIApp Business morto neste númeroDepois da CoexistênciaDuas superfíciesApp do WhatsApp BusinessAs mesmas conversas e o mesmo históricoCloud APINa mesma linhaAponte os eventos de mensagem para o seu próprio sistema
A Meta permite que um app substitua o destino de entrega dos webhooks de uma conta do WhatsApp Business específica. A gente define esse override para a sua URL, o que leva os dois campos do caminho das mensagens, messages e smb_message_echoes, direto da Meta para você.
Ficamos com os campos operacionais, porque é deles que o monitoramento é feito: account_update, phone_number_quality_update, account_alerts, account_review_update, business_capability_update e phone_number_name_update. Assim o painel continua útil enquanto o conteúdo das conversas nunca passa por nós.
Quais eventos vão para onde depois que o override está ativo. Eventos operacionaisEntregues para nósCaminho das mensagensEntregues para vocêmessagesTudo o que um cliente enviasmb_message_echoesO que a equipe envia pelo appSeu servidorDireto, nunca através de nósMantenha ativo, e sobreviva a uma reconexão
A Meta desconecta um número em Coexistência após cerca de catorze dias sem atividade no aparelho principal. Essa desconexão tem volta com uma reconexão, e a gente registra isso como um estado próprio em vez de tratar como um cliente indo embora.
O que pega as pessoas de surpresa é o que uma desconexão faz com a rota. A Meta guarda o destino como um override na assinatura do nosso app à conta, então um PARTNER_REMOVED desinstala o app e leva o override junto. Reconectar restaura o envio e o monitoramento, mas não o seu destino. A gente recoloca automaticamente, porque o primeiro número que bateu nessa regra reconectou sem problema e parou de entregar no servidor do cliente sem avisar.
O que uma reconexão restaura sozinha, e o que precisa ser recolocado. Restaurado pela MetaAutomáticoEnvioA Cloud API volta a funcionarEventos operacionaisO monitoramento é retomadoPerdido com o appPrecisa ser reaplicadoSeu override de webhookDesinstalado com o appEntrega de mensagens para vocêPara sem avisarA gente reaplicaEm toda reconexão
Por que times operam um número assim
- Manter o número que já está impresso em veículos, recibos e site, e o fluxo de trabalho no celular ao redor dele.
- Adicionar envio por API, processamento de webhook e templates sem mover ninguém para uma ferramenta nova.
- Manter o tráfego de mensagens fora da caixa compartilhada de um provedor, para que as conversas não fiquem na plataforma de outra empresa.
- Dar a uma agência uma forma de manter muitos números de clientes em uma conta, cada um conectado no Portfólio de Negócios do próprio cliente.
Elegibilidade e limites práticos
- O número precisa já estar ativo no app do WhatsApp Business. Um número no WhatsApp comum precisa ser movido para lá antes.
- Compartilhar o histórico de conversas é uma escolha única feita durante o onboarding e não pode ser alterada depois.
- Conversas em grupo ficam fora da API em números Coexistence, em qualquer provedor.
- O aparelho principal precisa de atividade periódica. A Meta desconecta após cerca de catorze dias sem ela.
- Caminhos de verificação e selo da Meta são diferentes para números Coexistence, e a disponibilidade regional muda conforme a política da Meta.
O que roteamos para você, e o que ficamos
A Meta permite que um app sobrescreva onde uma conta do WhatsApp Business entrega seus webhooks. A gente aponta esse override para a sua URL, o que divide os eventos em dois.
messagesTudo que um cliente envia para o númerosmb_message_echoesO que sua equipe envia pelo app do WhatsApp Business
account_updateEstado da conexão: removida, offboarded, reconectada, restritaphone_number_quality_updateMudanças de qualidade e throughputaccount_alertsAlertas que a Meta levanta contra a contaaccount_review_updateResultados de uma revisão da Metabusiness_capability_updateMudanças de limite de mensagens e capacidadesphone_number_name_updateAprovações e rejeições de nome de exibição
Se um número não tem override definido, seus eventos de mensagem caem no nosso callback padrão, onde o handler os descarta sem persistir. Isso é garantido em código e não prometido em política: não existe caminho de armazenamento para conteúdo de conversa seguir.
A regra dos catorze dias, e o que ela quebra que ninguém menciona
A Meta desconecta uma conexão Coexistence após cerca de catorze dias sem atividade no aparelho principal. É reconectável, então guardamos isso como estado próprio em vez de contar como cliente que foi embora.
A consequência que custa caro vem depois. O destino das suas mensagens não é uma configuração do número, é um override na assinatura do nosso app à conta do WhatsApp Business. Uma desconexão desinstala o app, e o override vai junto. Você reconecta, o envio volta, o monitoramento volta, e as mensagens param de chegar no seu servidor sem nada reportar erro.
A gente reaplica o override em toda reconexão. Esse comportamento existe porque aconteceu: um número bateu nessa regra, reconectou limpo, e parou de entregar calado.
Um handshake que falha naquele momento, porque seu servidor caiu ou o token mudou, fica registrado na linha do tempo da conexão e o destino é mantido em vez de descartado, então salvar de novo resolve.
O que quebra em silêncio, e como a gente descobre
O app do WhatsApp Business continua funcionando em quase todas as falhas abaixo, e é por isso que ninguém percebe. Estas são as que verificamos, e como.
Detectado pelo webhook account_update da Meta, especificamente PARTNER_REMOVED, em vez de inferido de um campo virando falso. A gente deliberadamente não lê is_on_biz_app para isso, porque ele é legitimamente falso em números que não são Coexistence e estava gerando desconexões falsas.
A regra de inatividade do aparelho principal da Meta. É reconectável, então fica registrada como estado próprio em vez de como cliente que saiu, e reconectar restaura envio e monitoramento.
O destino vive como override na assinatura do nosso app à conta, então uma desconexão o desinstala. O envio volta ao reconectar e a entrega no seu servidor não. A gente reaplica o override toda vez, porque um número a quem isso aconteceu reconectou limpo e parou de entregar calado.
Guardamos o token do cliente e o nosso System User token contra a mesma conta. Quando um é rejeitado, o outro lê a conta e decide qual dos dois realmente quebrou, então um token revogado deixa de parecer um número perdido.
Consultada da Meta periodicamente. Uma classificação RED marca a conexão como degradada, e qualidade, tier de mensagens e nível de throughput são gravados a cada verificação, então um declínio fica visível antes de custar um envio.
Conectar um número e vigiar um número são produtos diferentes. O segundo é a razão deste existir.
Tempo típico para conectar um número, escaneando um código no app do WhatsApp Business.
Quanto tempo a resposta de um cliente mantém a janela aberta para texto livre.
Throughput de envio de um número em Coexistência, fixado pela Meta e não elevável.
Quanto histórico de conversas a Meta sincroniza com a API quando um número conecta.
Perguntas frequentes
Minha equipe precisa parar de usar o celular?
Não. Esse é exatamente o ponto da Coexistência. O app do WhatsApp Business continua funcionando no mesmo número, com as mesmas conversas, e a API roda ao lado dele.
Vou perder minhas conversas atuais?
Não. Elas ficam no app, e a Meta sincroniza cerca de seis meses de histórico com a API quando o número conecta, então o software começa com contexto em vez de vazio.
Dá para desfazer?
Sim. Um número pode ser desconectado, e o app segue como sempre foi. Nada no número em si é alterado permanentemente por conectá-lo.
Isso é igual às APIs não oficiais de WhatsApp?
Não, e a diferença decide se o número sobrevive. A Coexistência é o recurso oficial da Meta na Cloud API. Gateways não oficiais controlam o WhatsApp Web como dispositivo vinculado, o que viola os termos e faz números serem banidos.
Pronto para começar?
Configure o WhatsApp Coexistence em minutos, não em meses. O aplicativo continua funcionando no celular.
Começar teste grátis3 dias grátis. Nada é cobrado até o teste terminar.