Como saber quando a ligação WhatsApp ou social de um cliente cai
A easyCoexistence envia à sua plataforma eventos de estado assinados quando a ligação de um cliente é estabelecida, cai, é removida ou suspensa. Um número WhatsApp envia connection.connected, connection.disconnected com o motivo da Meta, connection.removed, connection.suspended ou connection.token_missing; uma conta social envia os equivalentes channel.*, sem token_missing. Cada um é um POST JSON assinado com X-EC-Signature e repetido com intervalos crescentes durante cerca de 33 horas, até o seu endpoint responder 2xx.
PRIMARY_INACTIVITY: motivo da Meta quando o dispositivo principal esteve inativo durante cerca de 14 dias, desligando um número Coexistence.
COMPANION_INACTIVITY: motivo da Meta quando um dispositivo associado esteve inativo durante cerca de 30 dias.
O webhook que comunica uma desligação. A Meta envia-o sempre para o URL de callback predefinido da aplicação, nunca para um URL de substituição.
Frequência com que um evento de estado é tentado novamente após qualquer resposta fora de 2xx, com intervalos de 1 minuto a 24 horas, durante cerca de 33 horas.
Timestamp assinado t mais antigo que um endpoint deve aceitar num evento de estado, comparando o HMAC em tempo constante.
Que eventos de estado existem?
Nove, em duas famílias que partilham um endpoint e um segredo de assinatura. Os números usam connection.* e as contas sociais usam channel.*, pelo que um recetor escrito para números pode ignorar os eventos de canal pelo nome. Defina o endpoint no painel, em Perfil e depois Developers, ou com a ferramenta MCP set_partner_events_url; o segredo de assinatura é mostrado uma única vez, quando o URL é guardado.
O que transporta um evento de ligação?
O id da entrega, um UUID; o nome do evento; occurred_at em ISO 8601; e um objeto connection com id, external_ref, connect_session_id, phone, name, waba_id, phone_number_id, status e token_ready. Alguns eventos acrescentam um campo ao nível superior: reason em connection.disconnected e connection.suspended, detected_by com o valor health_check quando a verificação periódica da easyCoexistence encontrou a queda, em vez do webhook da Meta, e connect_session_id quando uma sessão de ligação originou o evento.
{
"id": "5c2a9e70-…",
"event": "connection.disconnected",
"occurred_at": "2026-10-31T10:15:02.114Z",
"connection": {
"id": "<CONNECTION_ID>",
"external_ref": "customer_4821",
"connect_session_id": "cs_…",
"phone": "+55 11 9…",
"name": "Clínica Sorriso",
"waba_id": "<WABA_ID>",
"phone_number_id": "<PHONE_NUMBER_ID>",
"status": "disconnected",
"token_ready": true
},
"reason": "PRIMARY_INACTIVITY"
}O que transporta um evento de canal?
O mesmo envelope, com um objeto channel no lugar de connection. É a vista de GET /channels/{id}: id, channel para a rede, external_ref, connect_session_id, name, username, external_id, status, token_ready, webhook_url, disconnected_reason, last_checked_at e created_at. Não existe token_missing para canais, já que um início de sessão social devolve sempre o token próprio do cliente, e um channel.connected originado por uma sessão de ligação também traz connect_session_id ao nível superior.
{
"id": "0b7e41d2-…",
"event": "channel.disconnected",
"occurred_at": "2026-10-31T10:15:02.114Z",
"channel": {
"id": "<CHANNEL_ID>",
"channel": "tiktok",
"external_ref": "customer_4821",
"connect_session_id": "cs_…",
"name": "Clínica Sorriso",
"username": "clinicasorriso",
"external_id": "<TIKTOK_OPEN_ID>",
"status": "disconnected",
"token_ready": false,
"webhook_url": "https://hooks.example.com/social",
"disconnected_reason": "<THE_NETWORK'S_MESSAGE>",
"last_checked_at": "2026-10-31T10:15:02.000Z",
"created_at": "2026-10-28T16:40:09.000Z"
}
}O que significam os motivos de desligação?
reason em connection.disconnected é o código que a Meta colocou em disconnection_info do seu webhook account_update, que a Meta inclui para números tanto na aplicação WhatsApp Business como na Cloud API. É null quando a Meta não indicou nenhum. Os códigos na referência da Meta:
PRIMARY_INACTIVITY: o telemóvel com a aplicação WhatsApp Business esteve inativo durante cerca de 14 dias, a regra dos 14 dias. Uma nova sessão de ligação volta a ligar o número.ACCOUNT_DISCONNECTED: a conta foi desligada através de medidas de aplicação da Meta ou pelo cliente, que pode ter removido o acesso ou eliminado a conta.COMPANION_INACTIVITY: um dispositivo associado esteve inativo durante cerca de 30 dias.BUSINESS_DOWNGRADE: o número estava registado na aplicação WhatsApp para consumidores.CHANGE_NUMBEReUSER_RE_REGISTERED: o cliente mudou o número, ou voltou a registá-lo num novo dispositivo.
Que cabeçalhos acompanham um evento de estado?
Cinco, em cada tentativa: Content-Type application/json, User-Agent easyCoexistence-webhooks/1, X-EC-Event com o nome do evento, X-EC-Delivery com o mesmo id do corpo, e X-EC-Signature. A assinatura lê-se t=<unix>,v1=<hex>, em que v1 é o HMAC-SHA256 de t, de um ponto e do corpo bruto, com a chave do segredo de assinatura da sua conta, que começa por whsec_. Cada tentativa é assinada de novo, pelo que uma repetição traz um novo t sobre o mesmo corpo.
import hashlib, hmac, json, os, time
SECRET = os.environ["EC_EVENTS_SECRET"].encode() # whsec_..., shown once in Profile > Developers
def verify(raw: bytes, header: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
t, v1 = parts.get("t", ""), parts.get("v1", "")
if not t.isdigit() or abs(time.time() - int(t)) > 300:
return False # missing, or more than 5 minutes off
mac = hmac.new(SECRET, t.encode() + b"." + raw, hashlib.sha256).hexdigest()
return hmac.compare_digest(mac, v1)
def handle(raw: bytes, headers) -> int:
if not verify(raw, headers.get("X-EC-Signature", "")):
return 401
event = json.loads(raw)
if already_processed(event["id"]): # the X-EC-Delivery id, the same on every retry
return 200
enqueue(event) # act on event["event"]; the latest occurred_at wins
return 200Como são repetidas as entregas falhadas?
A primeira tentativa sai no momento em que o evento acontece. Uma resposta fora de 2xx, a falta de resposta em 10 segundos, um erro de rede ou um redirecionamento contam como falha, e o evento é tentado de novo com intervalos crescentes, de 1 minuto a 24 horas, sete tentativas no total durante cerca de 33 horas, antes de ser descartado. As entregas vão só para um endereço HTTPS que resolva para um IP público. Um evento que ocorre enquanto não há endpoint definido nunca fica em fila, e remover o endpoint interrompe tudo o que estiver pendente.
Porque tratar cada id uma só vez e verificar occurred_at?
Porque uma repetição reenvia a entrega exatamente, com o mesmo id no corpo e em X-EC-Delivery, e porque um evento repetido pode chegar depois de um mais recente. Guarde os ids já processados e ignore os repetidos. Depois, compare occurred_at com o último estado registado para essa ligação, ou leia GET /connections/{id} ou GET /channels/{id} antes de agir sobre um evento que possa estar desatualizado.
O que deve fazer uma plataforma quando um número cai?
Agir conforme o motivo. Após PRIMARY_INACTIVITY, peça ao cliente que abra a aplicação WhatsApp Business e envie-lhe uma nova sessão de ligação para o mesmo número. Voltar a ligá-lo na mesma conta WhatsApp Business mantém o seu ID de ligação, repõe o destino do webhook e envia connection.connected, após o que deve voltar a ler as suas credenciais; connection.token_missing significa, em vez disso, que a Meta não emitiu token nessa execução. A Meta envia o account_update associado a uma queda apenas para o callback da própria aplicação, nunca para o seu URL, pelo que este evento é a forma como a sua plataforma fica a saber.
O que deve fazer uma plataforma quando uma conta social cai?
Em channel.disconnected, uma nova sessão de ligação com o mesmo canal volta a autenticar a conta, sob o mesmo ID de canal. channel.removed significa que o acesso deixou de existir: o token é esquecido e qualquer destino de webhook é limpo, pelo que deve voltar a definir o destino se o cliente se voltar a ligar. Um número ou canal suspenso volta a ficar disponível ao ligá-lo de novo, quando a sua subscrição estiver ativa outra vez.
Erros comuns
- Tratar uma repetição como um evento novo. Traz o mesmo id no corpo e em X-EC-Delivery, por isso registe os ids processados, ou uma só queda pode alertar um cliente duas vezes.
- Aplicar os eventos pela ordem de chegada. Um evento repetido pode chegar depois de um mais recente, por isso compare occurred_at ou leia a ligação antes de agir.
- Guardar outra vez o URL de eventos para corrigir um erro de escrita sem atualizar o backend. Guardar emite um novo segredo de assinatura, e todas as entregas falham a verificação até o seu endpoint passar a usá-lo.
- Fazer o trabalho antes de responder. Um manipulador que demore mais de 10 segundos conta como falhado e o evento volta, por isso responda 2xx primeiro e processe depois.
A easyCoexistence vigia a ligação WhatsApp e as contas sociais de cada cliente sem interrupção e envia à sua plataforma um evento assinado quando uma delas é ligada, cai, é removida ou suspensa, com o motivo da Meta quando um número cai. De US$ 9 a US$ 0.75 por ligação por mês, descendo à medida que acrescenta ligações, com os primeiros 3 dias grátis.
Perguntas frequentes
O que significa PRIMARY_INACTIVITY?
É o motivo da Meta para desligar um número Coexistence cuja aplicação WhatsApp Business esteve sem uso no dispositivo principal durante cerca de 14 dias. Uma nova sessão de ligação para esse cliente volta a ligar o número.
Os eventos de estado incluem mensagens?
Não. Cobrem o estado de uma ligação. As mensagens de um número vão da Meta para o destino de webhook próprio, e os comentários e mensagens diretas sociais para o destino de cada canal.
Onde defino o URL de eventos?
No painel, em Perfil e depois Developers, ou com a ferramenta MCP set_partner_events_url. O segredo de assinatura é mostrado uma única vez, e guardar o URL outra vez emite um novo.
Posso ignorar os eventos de canal se só trato números?
Sim. Os eventos channel.* têm nomes próprios e trazem um objeto channel em vez de connection, pelo que um recetor pode ignorar qualquer evento cujo nome não comece por connection.
Continue a ler
Ligue o seu primeiro canal em dois minutos.
Sem revisões de plataformas para esperar. Ligue o WhatsApp, o Instagram, o TikTok ou outro canal, peça depois à sua IA que publique, responda ou faça um relatório, e veja-a trabalhar.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorizado 24/7
Verificado em