Cómo saber cuándo se desconecta la conexión de WhatsApp o de una red social de un cliente
easyCoexistence envía a tu plataforma eventos de estado firmados cuando la conexión de un cliente se conecta, se desconecta, se elimina o se suspende. Un número de WhatsApp envía connection.connected, connection.disconnected con el motivo de Meta, connection.removed, connection.suspended o connection.token_missing; una cuenta de redes sociales envía los equivalentes channel.*, sin token_missing. Cada uno es un POST JSON firmado con X-EC-Signature y se reintenta con esperas crecientes durante unas 33 horas, hasta que tu endpoint responda 2xx.
PRIMARY_INACTIVITY: motivo de Meta cuando el dispositivo principal estuvo inactivo unos 14 días, lo que desconecta un número de Coexistencia.
COMPANION_INACTIVITY: motivo de Meta cuando un dispositivo complementario estuvo inactivo unos 30 días.
El webhook que informa una desconexión. Meta siempre lo envía a la URL de callback predeterminada de la app, nunca a una URL de callback alternativa.
Cada cuánto se reintenta un evento de estado tras cualquier respuesta distinta de 2xx, con esperas de 1 minuto a 24 horas, durante unas 33 horas.
Marca de tiempo firmada t más antigua que un endpoint debe aceptar en un evento de estado, comparando el HMAC en tiempo constante.
¿Qué eventos de estado existen?
Nueve, en dos familias que comparten un endpoint y un secreto de firma. Los números usan connection.* y las cuentas de redes sociales usan channel.*, así que un receptor escrito para números puede omitir los eventos de canal por nombre. Configura el endpoint en el panel, en Perfil y luego Desarrolladores, o con la herramienta MCP set_partner_events_url; el secreto de firma se muestra una sola vez, al guardar la URL.
¿Qué lleva un evento de conexión?
El id de la entrega, un UUID; el nombre del evento; occurred_at en ISO 8601; y un objeto connection con id, external_ref, connect_session_id, phone, name, waba_id, phone_number_id, status y token_ready. Algunos eventos añaden un campo de primer nivel: reason en connection.disconnected y connection.suspended, detected_by con el valor health_check cuando la comprobación periódica de easyCoexistence detectó la caída en lugar del webhook de Meta, y connect_session_id cuando una sesión de conexión generó el 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"
}¿Qué lleva un evento de canal?
La misma estructura, con un objeto channel en lugar de connection. Es la vista de GET /channels/{id}: id, channel para la red, external_ref, connect_session_id, name, username, external_id, status, token_ready, webhook_url, disconnected_reason, last_checked_at y created_at. No hay token_missing para canales, ya que un inicio de sesión en redes sociales siempre entrega el token propio del cliente, y un channel.connected que proviene de una sesión de conexión también lleva connect_session_id en el primer nivel.
{
"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"
}
}¿Qué significan los motivos de desconexión?
reason en connection.disconnected es el código que Meta puso en disconnection_info de su webhook account_update, que Meta incluye en los números tanto de la app de WhatsApp Business como de la Cloud API. Es null cuando Meta no dio ninguno. Los códigos de la referencia de Meta:
PRIMARY_INACTIVITY: el teléfono con la app de WhatsApp Business estuvo inactivo unos 14 días, la regla de los 14 días. Una nueva sesión de conexión reconecta el número.ACCOUNT_DISCONNECTED: la cuenta se desconectó por una medida de cumplimiento de Meta o por el cliente, que pudo haber quitado el acceso o eliminado la cuenta.COMPANION_INACTIVITY: un dispositivo complementario estuvo inactivo unos 30 días.BUSINESS_DOWNGRADE: el número estaba registrado en la app de WhatsApp para consumidores.CHANGE_NUMBERyUSER_RE_REGISTERED: el cliente cambió el número, o lo volvió a registrar en un dispositivo nuevo.
¿Qué encabezados llegan con un evento de estado?
Cinco, en cada intento: Content-Type application/json, User-Agent easyCoexistence-webhooks/1, X-EC-Event con el nombre del evento, X-EC-Delivery con el mismo id que el cuerpo, y X-EC-Signature. La firma tiene el formato t=<unix>,v1=<hex>, donde v1 es el HMAC-SHA256 de t, un punto y el cuerpo sin procesar, con la clave del secreto de firma de tu cuenta, que empieza por whsec_. Cada intento se firma de nuevo, así que un reintento lleva un t nuevo sobre el mismo cuerpo.
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 200¿Cómo se reintentan las entregas fallidas?
El primer intento sale en cuanto ocurre el evento. Una respuesta distinta de 2xx, ninguna respuesta en 10 segundos, un error de red o una redirección cuentan como fallo, y el evento se vuelve a intentar con esperas crecientes, de 1 minuto a 24 horas: siete intentos en total durante unas 33 horas, antes de descartarse. Las entregas solo van a una dirección HTTPS que resuelve a una IP pública. Un evento que ocurre mientras no hay endpoint configurado nunca se pone en cola, y eliminar el endpoint detiene lo que esté pendiente.
¿Por qué procesar cada id una sola vez y revisar occurred_at?
Porque un reintento repite la entrega exactamente, con el mismo id en el cuerpo y en X-EC-Delivery, y porque un evento reintentado puede llegar después de uno más reciente. Guarda los ids que ya procesaste y omite los repetidos. Luego compara occurred_at con el último estado que registraste para esa conexión, o lee GET /connections/{id} o GET /channels/{id} antes de actuar sobre un evento que podría estar desactualizado.
¿Qué debe hacer una plataforma cuando cae un número?
Actuar según el motivo. Tras PRIMARY_INACTIVITY, pide al cliente que abra la app de WhatsApp Business y envíale una nueva sesión de conexión para el mismo número. Reconectarlo en la misma cuenta de WhatsApp Business conserva su ID de conexión, restaura el destino de tu webhook y envía connection.connected; después vuelves a leer sus credenciales. connection.token_missing, en cambio, significa que Meta no emitió token en esa operación. Meta envía el account_update que provoca una caída solo al callback de la app, nunca a tu URL, así que este evento es la forma en que tu plataforma se entera.
¿Qué debe hacer una plataforma cuando cae una cuenta de redes sociales?
Con channel.disconnected, una nueva sesión de conexión con el mismo canal vuelve a iniciar sesión en la cuenta, bajo el mismo ID de canal. channel.removed significa que el acceso se perdió: el token se olvida y se borra el destino del webhook, así que vuelve a configurarlo si el cliente se reconecta. Un número o canal suspendido vuelve al reconectarlo una vez que tu suscripción esté activa de nuevo.
Errores comunes
- Tratar un reintento como un evento nuevo. Lleva el mismo id en el cuerpo y en X-EC-Delivery, así que registra los ids procesados, o una sola caída puede alertar dos veces a un cliente.
- Aplicar los eventos en orden de llegada. Un evento reintentado puede llegar después de uno más reciente, así que compara occurred_at o lee la conexión antes de actuar.
- Volver a guardar la URL de eventos para corregir una errata sin actualizar el backend. Guardar emite un nuevo secreto de firma, y cada entrega falla la verificación hasta que tu endpoint lo use.
- Hacer el trabajo antes de responder. Un handler que tarda más de 10 segundos cuenta como fallido y el evento vuelve, así que responde 2xx primero y procesa después.
easyCoexistence vigila el número de WhatsApp y las cuentas de redes sociales de cada cliente en todo momento, y envía a tu plataforma un evento firmado cuando una se conecta, se desconecta, se elimina o se suspende, con el motivo de Meta cuando un número se cae. De US$ 9 a US$ 0.75 por conexión al mes, con una tarifa que baja a medida que añades conexiones, y los primeros 3 días gratis.
Preguntas frecuentes
¿Qué significa PRIMARY_INACTIVITY?
Es el motivo de Meta para desconectar un número de Coexistencia cuya app de WhatsApp Business no se usó en su dispositivo principal durante unos 14 días. Una nueva sesión de conexión para ese cliente reconecta el número.
¿Los eventos de estado incluyen mensajes?
No. Cubren el estado de una conexión. Los mensajes de un número van de Meta a su propio destino de webhook, y los comentarios y mensajes directos de redes sociales van al destino de cada canal.
¿Dónde configuro la URL de eventos?
En el panel, en Perfil y luego Desarrolladores, o con la herramienta MCP set_partner_events_url. El secreto de firma se muestra una vez, y volver a guardar la URL emite uno nuevo.
¿Puedo ignorar los eventos de canal si solo manejo números?
Sí. Los eventos channel.* tienen nombres propios y llevan un objeto channel en lugar de connection, así que un receptor puede omitir cualquier evento cuyo nombre no empiece por connection.
Sigue leyendo
Conecta tu primer canal en dos minutos.
Sin esperar revisiones de las plataformas. Conecta WhatsApp, Instagram, TikTok u otro canal, pídele a tu IA que publique, responda o te haga un informe, y míralo trabajar.
- 3 días gratis
- Cancela cuando quieras
- Solo APIs oficiales
- Monitorizado 24/7
Verificado el