Um número.A app e a API, em simultâneo.
A Coexistência é o modo oficial da Meta para usar a app do WhatsApp Business e a Cloud API no mesmo número em simultâneo. A equipa continua a responder pelo telemóvel, com as mesmas conversas e o mesmo histórico, enquanto o software envia e recebe na mesma linha.
A EasyCoexistence liga o número e monitoriza a ligação.
A escolha que existia, e que já não existe
A Coexistência não é uma API nova. É o fim de uma bifurcação que impedia quase todas as pequenas empresas de automatizar fosse o que fosse.
A equipa responde pelo telemóvel. Nada pode ser automatizado, integrado ou medido.
Sem APIO software chega ao número. A app Business deixa de funcionar nesse número e a equipa muda de ferramenta.
Sem appA Meta liga a Cloud API a um número que a app do WhatsApp Business continua a usar. As duas superfícies ficam ativas na mesma linha, e cada uma vê o que a outra envia.
Quem usa um número desta forma
Dois grupos que querem coisas opostas da mesma funcionalidade, e é por isso que a ligação importa mais do que qualquer painel construído por cima dela.
Uma equipa pequena, um número pintado numa carrinha ou numa montra, e noites passadas a responder às mesmas quatro perguntas. Não se trata de substituir ninguém. O que se quer é que confirmações, lembretes e a primeira resposta fora de horas aconteçam sem uma pessoa, enquanto o telemóvel continua a servir para tudo o resto.
Muitos clientes, cada um com um número que ninguém pode migrar nem tocar. Esses números têm de estar ao alcance dos sistemas que constroem, e o seguinte tem de poder ser adicionado sem uma chamada comercial. A Coexistência é o único caminho oficial para um número a que a equipa do cliente ainda responde à mão.
Como um número passa a estar nos dois, e para onde vão os eventos de mensagens
Quatro passos. O único que mexe no telemóvel é a leitura de um código, e o que decide a sua arquitetura é o primeiro.
Tenha o endpoint pronto antes de o processo de ligação começar
A Meta verifica um destino antes de lhe entregar seja o que for. Chama o seu URL com um GET que leva hub.mode=subscribe, o seu hub.verify_token e um hub.challenge, e o seu endpoint tem de devolver o hub.challenge exatamente como o recebeu.
O destino tem de ser HTTPS, e o token de verificação é obrigatório. Validamos ambos antes de a chamada ser feita, por isso um URL mal formado falha à nossa porta em vez de parecer ligado e não entregar nada.
Ainda nada está ligado. É isto que decide onde as mensagens vão chegar. Fornecedor no caminhoGuardado nos servidores deleA plataforma deleRecebe e guarda as mensagensA sua empresaUma cópia, ao ritmo deleEasyCoexistenceApenas configuraçãoO seu endpointAinda não verificadoNósDefinimos a rota, não estamos nelaExecute o Embedded Signup da Meta e leia o código na app
Abre-se a janela da própria Meta. Escolhe o Portefólio empresarial, a WhatsApp Business Account e o número já registado na app do WhatsApp Business, e depois aprova a ligação no telemóvel através da leitura de um código.
É também aqui que escolhe se partilha o histórico de conversas existente. É uma decisão tomada uma única vez no processo de ligação e não pode ser alterada depois. A app Business continua a funcionar no momento em que a leitura termina.
Aparece a segunda superfície. A primeira não é removida. Depois de uma migraçãoUma superfícieSó Cloud APIApp Business morta neste númeroDepois da CoexistênciaDuas superfíciesApp do WhatsApp BusinessAs mesmas conversas e o mesmo históricoCloud APINa mesma linhaAponte os eventos de mensagens para o seu próprio sistema
A Meta permite que uma app substitua o destino para onde são entregues os webhooks de uma determinada WhatsApp Business Account. Definimos esse override para o seu URL, o que faz os dois campos do caminho das mensagens, messages e smb_message_echoes, seguirem diretamente da Meta para si.
Ficamos com os campos operacionais, porque é deles que a monitorização é feita: account_update, phone_number_quality_update, account_alerts, account_review_update, business_capability_update e phone_number_name_update. Assim o painel continua útil sem que o conteúdo das conversas alguma vez passe por nós.
Que eventos vão para onde quando o override está ativo. Eventos operacionaisEntregues a nósCaminho das mensagensEntregues a simessagesTudo o que um cliente enviasmb_message_echoesO que a equipa envia a partir da appO seu servidorDiretamente, nunca através de nósMantenha-o ativo, e sobreviva a uma nova ligação
A Meta desliga um número em Coexistência ao fim de cerca de catorze dias sem atividade no dispositivo principal. O número pode voltar a ser ligado, e registamos esse desligamento como um estado próprio em vez de o tratar como um cliente que sai.
O que apanha as pessoas desprevenidas é o que um desligamento faz à rota. A Meta guarda o destino como um override na subscrição da nossa app à conta, por isso um PARTNER_REMOVED desinstala a app e leva o override com ela. Voltar a ligar repõe o envio e a monitorização, mas não o seu destino. Repomo-lo automaticamente, porque o primeiro número que esbarrou nesta regra voltou a ser ligado sem problemas e deixou de entregar ao servidor do cliente, sem qualquer aviso.
O que uma nova ligação repõe sozinha, e o que tem de ser reposto. Reposto pela MetaAutomáticoEnvioA Cloud API volta a funcionarEventos operacionaisA monitorização é retomadaPerdido com a appTem de ser reaplicadoO seu override de webhookDesinstalado com a appEntrega de mensagens a siPara sem avisoNós reaplicamo-loEm cada nova ligação
Porque é que as equipas usam um número desta forma
- Manter o número que já está pintado nas carrinhas, impresso nos recibos e no site, e o trabalho no telemóvel organizado à volta dele.
- Acrescentar envio pela API, processamento de webhooks e templates sem mudar ninguém para uma ferramenta nova.
- Manter o tráfego de mensagens fora da caixa de entrada partilhada de um fornecedor, para que as conversas não fiquem na plataforma de outra empresa.
- Dar a uma agência forma de gerir os números de muitos clientes numa só conta, cada um ligado no Portefólio empresarial do próprio cliente.
Elegibilidade e limites práticos
- O número tem de estar já ativo na app do WhatsApp Business. Um número na app de consumo do WhatsApp tem de ser transferido para lá primeiro.
- Partilhar o histórico de conversas existente é uma escolha única feita durante o onboarding e não pode ser alterada depois.
- As conversas de grupo ficam excluídas da API nos números em Coexistência, em todos os fornecedores.
- O dispositivo principal precisa de atividade periódica. A Meta desliga a ligação ao fim de cerca de catorze dias sem ela.
- Os percursos de verificação e de selo da Meta são diferentes para números em Coexistência, e a disponibilidade regional muda com a política da Meta.
O que encaminhamos para si, e o que guardamos
A Meta permite que uma app substitua o destino para onde uma WhatsApp Business Account entrega os seus webhooks. Apontamos esse override para o seu URL, o que divide os eventos em dois.
messagesTudo o que um cliente envia para o númerosmb_message_echoesO que a sua equipa envia a partir da app do WhatsApp Business
account_updateEstado da ligação: removida, desvinculada, religada, restringidaphone_number_quality_updateAlterações na classificação de qualidade e no throughputaccount_alertsAlertas que a Meta levanta sobre a contaaccount_review_updateResultados de uma revisão da Metabusiness_capability_updateAlterações no limite de mensagens e nas capacidadesphone_number_name_updateAprovações e rejeições do nome a apresentar
Se um número não tiver override definido, os seus eventos de mensagem caem no nosso callback predefinido, onde o handler os descarta sem os guardar. Isto é imposto no código e não prometido numa política: não existe nenhum caminho de armazenamento que o conteúdo das conversas possa seguir.
A regra dos catorze dias, e o que ela estraga sem que ninguém o diga
A Meta desliga uma ligação de Coexistência ao fim de cerca de catorze dias sem atividade no dispositivo principal. Pode voltar a ser ligada, por isso guardamo-la como um estado próprio em vez de a contar como um cliente que saiu.
A consequência que sai cara vem depois. O destino das suas mensagens não é uma definição do número, é um override na subscrição da nossa app à WhatsApp Business Account. Um desligamento desinstala a app, e o override desaparece com ela. Volta a ligar, o envio funciona, a monitorização funciona, e as mensagens deixam de chegar ao seu servidor sem que nada assinale um erro.
Voltamos a aplicar o override em cada nova ligação. Este comportamento existe porque aconteceu: um número foi apanhado por esta regra, voltou a ligar-se sem problemas e deixou de entregar em silêncio.
Se o handshake falhar nesse momento, porque o seu servidor estava em baixo ou o token mudou, isso fica registado na cronologia da ligação e o destino é mantido em vez de descartado, por isso basta guardá-lo de novo para resolver.
O que falha em silêncio, e como damos por isso
A app do WhatsApp Business continua a funcionar em quase todas as falhas abaixo, e é por isso que ninguém repara. Estas são as que verificamos, e como.
Detetado pelo webhook account_update da Meta, concretamente PARTNER_REMOVED, em vez de deduzido de um campo que passa a false. Não lemos deliberadamente is_on_biz_app para isto, porque é legitimamente false em números que não estão em Coexistência e estava a provocar falsos desligamentos.
A regra de inatividade do dispositivo principal da Meta. Pode voltar a ser ligada, por isso fica registada como um estado próprio e não como um cliente que saiu, e voltar a ligar repõe o envio e a monitorização.
O destino existe como override na subscrição da nossa app à conta, por isso um desligamento desinstala-o. O envio volta com a nova ligação e a entrega no seu servidor não. Voltamos a aplicar o override sempre, porque um número a quem isto aconteceu voltou a ligar-se sem problemas e deixou de entregar em silêncio.
Guardamos o token do cliente e o nosso próprio System User token sobre a mesma conta. Quando um é rejeitado, o outro lê a conta e determina qual dos dois falhou de facto, por isso um token revogado já não parece um número perdido.
Consultada à Meta periodicamente. Uma classificação RED marca a ligação como degradada, e a qualidade, o nível de mensagens e o nível de throughput são guardados em cada verificação, para que uma descida seja visível antes de custar um envio.
Ligar um número e vigiar um número são produtos diferentes. O segundo é a razão de este existir.
Tempo habitual para ligar um número, lendo um código na app WhatsApp Business.
Durante quanto tempo uma resposta do cliente mantém a sessão aberta para respostas em texto livre.
Throughput de envio de um número em Coexistência, definido pela Meta e não aumentável.
Quantidade de histórico de conversas que a Meta sincroniza com a API quando um número é ligado pela primeira vez.
Perguntas frequentes
A minha equipa tem de deixar de usar o telemóvel?
Não. Esse é precisamente o objetivo da Coexistência. A app WhatsApp Business continua a funcionar no mesmo número, com as mesmas conversas, e a API funciona em paralelo.
Vou perder as conversas que já existem?
Não. Ficam na app e a Meta sincroniza cerca de seis meses de histórico com a API quando o número é ligado, para que o software tenha contexto em vez de começar vazio.
Posso desfazer a ligação?
Sim. Um número pode ser desligado e a app continua a funcionar como sempre. Ligar o número não o altera permanentemente.
É o mesmo que as APIs não oficiais do WhatsApp?
Não, e essa diferença determina se o número sobrevive. A Coexistência é uma funcionalidade oficial da Meta na Cloud API. Os gateways não oficiais controlam o WhatsApp Web como dispositivo ligado, violam os termos e fazem com que os números sejam banidos.
Pronto para começar?
Configure a Coexistência do WhatsApp em minutos, não em meses. A aplicação continua a funcionar no telemóvel.
Iniciar teste gratuito3 dias grátis. Nada é cobrado até ao fim do período de teste.