Como saber quando a conexão do WhatsApp ou de uma rede social de um cliente cai
A easyCoexistence envia eventos de status assinados pela plataforma quando a conexão de um cliente é conectada, cai, é removida ou é suspensa. Um número de WhatsApp envia connection.connected, connection.disconnected com o motivo da Meta, connection.removed, connection.suspended ou connection.token_missing; uma conta de rede social envia os equivalentes channel.*, sem token_missing. Cada um é um POST em JSON assinado com X-EC-Signature e repetido com intervalos crescentes por cerca de 33 horas, até que seu endpoint responda 2xx.
PRIMARY_INACTIVITY: motivo da Meta quando o dispositivo principal ficou inativo por aproximadamente 14 dias, desconectando um número de Coexistência.
COMPANION_INACTIVITY: motivo da Meta quando um dispositivo companheiro ficou inativo por aproximadamente 30 dias.
O webhook que informa uma desconexão. A Meta sempre o envia para a URL de callback padrão do app, nunca para uma URL alternativa.
Com que frequência um evento de status é repetido após qualquer resposta fora de 2xx, com intervalos de 1 minuto a 24 horas, por cerca de 33 horas.
Timestamp assinado t mais antigo que um endpoint deve aceitar em um evento de status, comparando o HMAC em tempo constante.
Quais são os eventos de status?
Nove, em duas famílias que compartilham um endpoint e um segredo de assinatura. Números usam connection.* e contas de redes sociais usam channel.*, então um receptor escrito para números pode ignorar eventos de canal pelo nome. Configure o endpoint no painel em Perfil e depois Desenvolvedores, ou com a ferramenta MCP set_partner_events_url; o segredo de assinatura é exibido uma única vez, quando a URL é salva.
O que um evento de conexão traz?
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 no nível superior: reason em connection.disconnected e connection.suspended; detected_by com o valor health_check quando a verificação periódica própria da easyCoexistence identificou a queda, e não o webhook da Meta; e connect_session_id quando uma sessão de conexão gerou 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 um evento de canal traz?
O mesmo envelope, com um objeto channel no lugar de connection. É a visão 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, porque um login em rede social sempre entrega o token próprio do cliente. Um channel.connected que veio de uma sessão de conexão também traz connect_session_id no 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 desconexã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 no app do WhatsApp Business quanto na Cloud API. É null quando a Meta não informou nenhum. Os códigos na referência da Meta:
PRIMARY_INACTIVITY: o telefone com o app do WhatsApp Business ficou inativo por cerca de 14 dias, a regra dos 14 dias. Uma nova sessão de conexão reconecta o número.ACCOUNT_DISCONNECTED: a conta foi desconectada pela aplicação de políticas da Meta ou pelo cliente, que pode ter removido o acesso ou excluído a conta.COMPANION_INACTIVITY: um dispositivo companheiro ficou inativo por cerca de 30 dias.BUSINESS_DOWNGRADE: o número foi registrado no app consumidor do WhatsApp.CHANGE_NUMBEReUSER_RE_REGISTERED: o cliente trocou o número ou o registrou novamente em um novo dispositivo.
Quais cabeçalhos acompanham um evento de status?
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 tem a forma t=<unix>,v1=<hex>, em que v1 é o HMAC-SHA256 de t, um ponto e o corpo bruto, usando como chave o segredo de assinatura da sua conta, que começa com whsec_. Cada tentativa é assinada de novo, então 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 as entregas com falha são repetidas?
A primeira tentativa sai no momento em que o evento acontece. Uma resposta fora de 2xx, nenhuma resposta em 10 segundos, um erro de rede ou um redirecionamento conta como falha, e o evento é repetido com intervalos crescentes, de 1 minuto a 24 horas, sete tentativas no total por cerca de 33 horas, antes de ser descartado. As entregas vão só para um endereço HTTPS que resolve para um IP público. Um evento que acontece enquanto nenhum endpoint está configurado nunca entra em fila, e remover o endpoint interrompe tudo o que estiver pendente.
Por que tratar cada id uma 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 que você já processou e ignore as repetições. Depois compare occurred_at com o último estado registrado para aquela conexão, ou leia GET /connections/{id} ou GET /channels/{id} antes de agir sobre um evento que pode estar desatualizado.
O que uma plataforma deve fazer quando um número cai?
Agir conforme o motivo. Após PRIMARY_INACTIVITY, peça ao cliente que abra o app do WhatsApp Business e gere para ele uma nova sessão de conexão para o mesmo número. Reconectá-lo na mesma WhatsApp Business Account mantém o ID de conexão, recoloca o destino do seu webhook e envia connection.connected; depois disso, leia as credenciais dele de novo. Já connection.token_missing significa que a Meta não emitiu token nessa execução. A Meta envia o account_update que sinaliza a queda apenas para o callback do próprio app, nunca para a sua URL, então este evento é como a sua plataforma fica sabendo dela.
O que uma plataforma deve fazer quando uma conta de rede social cai?
Em channel.disconnected, uma nova sessão de conexão para o mesmo canal faz login na conta de novo, sob o mesmo ID de canal. channel.removed significa que o acesso foi perdido: o token é esquecido e qualquer destino de webhook é apagado, então defina o destino novamente se o cliente reconectar. Um número ou canal suspenso volta ao ser reconectado, depois que a assinatura estiver ativa de novo.
Erros comuns
- Tratar uma repetição como um evento novo. Ela traz o mesmo id no corpo e em X-EC-Delivery, então registre os ids processados, ou uma única queda pode alertar um cliente duas vezes.
- Aplicar eventos na ordem de chegada. Um evento repetido pode chegar depois de um mais recente, então compare occurred_at ou leia a conexão antes de agir.
- Salvar a URL de eventos de novo para corrigir um erro de digitação sem atualizar o backend. Salvar emite um novo segredo de assinatura, e toda entrega falha na verificação até que o seu endpoint use esse segredo.
- Fazer o trabalho antes de responder. Um handler que leva mais de 10 segundos conta como falha e o evento volta, então responda 2xx primeiro e processe depois.
A easyCoexistence acompanha o número de WhatsApp e as contas de redes sociais de cada cliente o tempo todo e envia à sua plataforma um evento assinado quando um deles é conectado, cai, é removido ou é suspenso, com o motivo da Meta para um número que cai. De US$ 9 a US$ 0.75 por conexão por mês, com valor caindo à medida que você adiciona conexões, e os primeiros 3 dias grátis.
O easyCoexistence é uma API e um servidor MCP multicanal que conecta agentes de IA, como o Claude e o ChatGPT, ao WhatsApp, Instagram, TikTok, Facebook e mais. No WhatsApp, ele usa o Coexistence: a empresa continua usando o número no app WhatsApp Business enquanto a IA trabalha pela API oficial da Meta.
Perguntas frequentes
O que significa PRIMARY_INACTIVITY?
É o motivo da Meta para desconectar um número de Coexistência cujo app do WhatsApp Business ficou sem uso no dispositivo principal por cerca de 14 dias. Uma nova sessão de conexão para esse cliente reconecta o número.
Os eventos de status incluem mensagens?
Não. Eles cobrem o status de uma conexão. As mensagens de um número vão da Meta para o destino de webhook próprio dele, e os comentários e DMs de redes sociais vão para o destino de cada canal.
Onde configuro a URL de eventos?
No painel, em Perfil e depois Desenvolvedores, ou com a ferramenta MCP set_partner_events_url. O segredo de assinatura é exibido uma única vez, e salvar a URL de novo emite um novo.
Posso ignorar eventos de canal se eu só trato números?
Sim. Os eventos channel.* têm nomes próprios e trazem um objeto channel no lugar de connection, então um receptor pode ignorar qualquer evento cujo nome não comece com connection.
Continue lendo
Conecte seu primeiro canal em dois minutos.
Sem esperar aprovação das plataformas. Conecte o WhatsApp, o Instagram, o TikTok ou outro canal, peça para a sua IA publicar, responder ou trazer os números, e veja funcionando.
- 3 dias grátis
- Cancele quando quiser
- Só APIs oficiais
- Monitorado 24/7
Verificado em