Iniciar sessãoIniciar teste gratuito
Meta Tech Provider

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.

Iniciar teste gratuito3 dias grátis. Nada é cobrado até ao fim do período de teste.
+1 415 555 0188
App do WhatsApp BusinessA equipa responde pelo telemóvel, como antes
Cloud APIOs seus sistemas, ou um assistente de IA, na mesma linha
As duas superfícies veem a mesma conversa. O que a API envia aparece na app, e o que a equipa escreve na app chega como um evento smb_message_echoes, por isso o software nunca responde por cima de uma pessoa que já respondeu.
Sem guardar mensagens por defeitoAplicação Business + Cloud APIMCP para Claude e ChatGPTPronto em 2 minutos

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.

AntesUm número, uma escolha
Manter a app

A equipa responde pelo telemóvel. Nada pode ser automatizado, integrado ou medido.

Sem API
Migrar para a API

O software chega ao número. A app Business deixa de funcionar nesse número e a equipa muda de ferramenta.

Sem app
AgoraUm número, as duas
Um número
App do WhatsApp BusinessCloud API

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

Mantém o telemóvelUma empresa com um número

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 números, uma contaUma agência, consultora ou programador

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.

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

    Requer
    Um endpoint HTTPS que devolve o hub.challenge no GET da Meta
    Tempo
    Cerca de um minuto
    Obtém
    Um destino que a Meta consegue verificar no momento em que o número é ligado
    Ainda nada está ligado. É isto que decide onde as mensagens vão chegar.
    Fornecedor no caminhoGuardado nos servidores dele
    Meta
    A plataforma deleRecebe e guarda as mensagens
    A sua empresaUma cópia, ao ritmo dele
    EasyCoexistenceApenas configuração
    Meta
    O seu endpointAinda não verificado
    NósDefinimos a rota, não estamos nela
  2. Execute 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.

    Requer
    Acesso ao Portefólio empresarial, e o telemóvel com o número
    Tempo
    Dois a três minutos
    Obtém
    A Cloud API ligada a um número que a app continua a usar
    Aparece a segunda superfície. A primeira não é removida.
    Depois de uma migraçãoUma superfície
    O número
    Só Cloud APIApp Business morta neste número
    Depois da CoexistênciaDuas superfícies
    O número
    App do WhatsApp BusinessAs mesmas conversas e o mesmo histórico
    Cloud APINa mesma linha
  3. Aponte 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.

    Requer
    O endpoint do primeiro passo, agora verificado pela Meta
    Tempo
    Aplicado assim que o processo de ligação termina
    Obtém
    Mensagens entregues da Meta para si, connosco fora do caminho das mensagens
    Que eventos vão para onde quando o override está ativo.
    Eventos operacionaisEntregues a nós
    account_updateMudanças de estado da ligação
    phone_number_quality_updateQualidade e throughput
    account_review_updateResultados de revisões
    Caminho das mensagensEntregues a si
    messagesTudo o que um cliente envia
    smb_message_echoesO que a equipa envia a partir da app
    O seu servidorDiretamente, nunca através de nós
  4. Mantenha-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.

    Requer
    A app aberta no dispositivo principal de vez em quando
    Tempo
    Contínuo
    Obtém
    Uma ligação vigiada, e uma rota que sobrevive a uma nova ligação
    O que uma nova ligação repõe sozinha, e o que tem de ser reposto.
    Reposto pela MetaAutomático
    EnvioA Cloud API volta a funcionar
    Eventos operacionaisA monitorização é retomada
    Perdido com a appTem de ser reaplicado
    O seu override de webhookDesinstalado com a app
    Entrega de mensagens a siPara sem aviso
    Nó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.
Texto livre0 a 24 horas após a última mensagem do clienteSó templatedepois disso, até o cliente voltar a escrever
O relógio recomeça sempre que o cliente envia alguma coisa. É a regra que estraga integrações em produção, porque os testes acontecem sempre segundos depois de uma mensagem, quando o texto livre ainda funciona.

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.

Entregues diretamente no seu endpointO caminho das mensagens. Por predefinição, nunca passa por nós.
  • messagesTudo o que um cliente envia para o número
  • smb_message_echoesO que a sua equipa envia a partir da app do WhatsApp Business
Entregues a nósO caminho operacional. É disto que a monitorização é feita.
  • account_updateEstado da ligação: removida, desvinculada, religada, restringida
  • phone_number_quality_updateAlterações na classificação de qualidade e no throughput
  • account_alertsAlertas que a Meta levanta sobre a conta
  • account_review_updateResultados de uma revisão da Meta
  • business_capability_updateAlterações no limite de mensagens e nas capacidades
  • phone_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.

O número foi desligadoWebhook, fonte fiável

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 ligação esteve inativa durante catorze diasEstado próprio

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.

A sua rota de webhook desapareceu ao voltar a ligarReaplicado automaticamente

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.

O token de acesso deixou de funcionarDois tokens, uma resposta

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.

A qualidade desceuConsultado

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.

2 minutes

Tempo habitual para ligar um número, lendo um código na app WhatsApp Business.

24 hours

Durante quanto tempo uma resposta do cliente mantém a sessão aberta para respostas em texto livre.

20 msg/s

Throughput de envio de um número em Coexistência, definido pela Meta e não aumentável.

6 months

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.

Continue a ler