Come sapere quando la connessione WhatsApp o social di un cliente si interrompe
easyCoexistence invia alla tua piattaforma eventi di stato firmati quando la connessione di un cliente si connette, si interrompe, viene rimossa o sospesa. Un numero WhatsApp invia connection.connected, connection.disconnected con il motivo di Meta, connection.removed, connection.suspended o connection.token_missing; un account social invia gli equivalenti channel.*, senza token_missing. Ogni evento è un POST JSON firmato con X-EC-Signature e ritentato con intervalli crescenti per circa 33 ore, finché il tuo endpoint non risponde 2xx.
PRIMARY_INACTIVITY: motivo di Meta quando il dispositivo principale è rimasto inattivo per circa 14 giorni, disconnettendo un numero Coexistence.
COMPANION_INACTIVITY: motivo di Meta quando un dispositivo companion è rimasto inattivo per circa 30 giorni.
Il webhook che segnala una disconnessione. Meta lo invia sempre all'URL di callback predefinito dell'app, mai a un URL alternativo.
Quanto spesso viene ritentato un evento di stato dopo una risposta diversa da 2xx, con intervalli da 1 minuto a 24 ore, per circa 33 ore.
Il timestamp firmato t più vecchio che un endpoint deve accettare per un evento di stato, confrontando l'HMAC in tempo costante.
Quali sono gli eventi di stato?
Nove, in due famiglie che condividono un solo endpoint e un solo segreto di firma. I numeri usano connection.* e gli account social usano channel.*, quindi un ricevitore scritto per i numeri può ignorare per nome gli eventi channel. Imposta l'endpoint nella dashboard sotto Profilo, poi Developers, oppure con lo strumento MCP set_partner_events_url; il segreto di firma viene mostrato una sola volta, al salvataggio dell'URL.
Cosa contiene un evento di connessione?
L'id della consegna, un UUID; il nome dell'evento; occurred_at in ISO 8601; e un oggetto connection con id, external_ref, connect_session_id, phone, name, waba_id, phone_number_id, status e token_ready. Alcuni eventi aggiungono un campo di primo livello: reason su connection.disconnected e connection.suspended, detected_by impostato su health_check quando il controllo periodico di easyCoexistence ha rilevato la caduta invece del webhook di Meta, e connect_session_id quando una sessione di connessione ha prodotto l'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"
}Cosa contiene un evento channel?
La stessa struttura, con un oggetto channel al posto di connection. È la vista di GET /channels/{id}: id, channel per la rete, external_ref, connect_session_id, name, username, external_id, status, token_ready, webhook_url, disconnected_reason, last_checked_at e created_at. Per i canali non esiste token_missing, perché un accesso social restituisce sempre il token proprio del cliente; un channel.connected proveniente da una sessione di connessione porta anche connect_session_id di primo livello.
{
"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"
}
}Cosa significano i motivi di disconnessione?
reason su connection.disconnected è il codice che Meta ha inserito in disconnection_info del suo webhook account_update, che Meta include per i numeri sia nell'app WhatsApp Business sia nella Cloud API. È null quando Meta non ne ha forniti. I codici nel riferimento di Meta:
PRIMARY_INACTIVITY: il telefono con l'app WhatsApp Business è rimasto inattivo per circa 14 giorni, la regola dei 14 giorni. Una nuova sessione di connessione riconnette il numero.ACCOUNT_DISCONNECTED: l'account è stato disconnesso per provvedimento di Meta o dal cliente, che può aver revocato l'accesso o eliminato l'account.COMPANION_INACTIVITY: un dispositivo companion è rimasto inattivo per circa 30 giorni.BUSINESS_DOWNGRADE: il numero era registrato con l'app WhatsApp dei consumatori.CHANGE_NUMBEReUSER_RE_REGISTERED: il cliente ha cambiato numero, oppure lo ha registrato di nuovo su un nuovo dispositivo.
Quali header arrivano con un evento di stato?
Cinque, a ogni tentativo: Content-Type application/json, User-Agent easyCoexistence-webhooks/1, X-EC-Event con il nome dell'evento, X-EC-Delivery con lo stesso id del corpo, e X-EC-Signature. La firma ha la forma t=<unix>,v1=<hex>, dove v1 è l'HMAC-SHA256 di t, un punto e il corpo grezzo, con chiave il segreto di firma del tuo account, che inizia con whsec_. Ogni tentativo viene firmato di nuovo, quindi un nuovo tentativo porta un nuovo t sullo stesso 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 200Come vengono ritentate le consegne fallite?
Il primo tentativo parte nel momento in cui l'evento accade. Una risposta diversa da 2xx, nessuna risposta entro 10 secondi, un errore di rete o un redirect conta come fallimento, e l'evento viene ritentato con intervalli crescenti, da 1 minuto a 24 ore, sette tentativi in tutto in circa 33 ore, prima di essere scartato. Le consegne partono solo verso un indirizzo HTTPS che risolve in un IP pubblico. Un evento che accade mentre non è impostato alcun endpoint non viene mai accodato, e rimuovere l'endpoint interrompe tutto ciò che è in sospeso.
Perché gestire ogni id una sola volta e controllare occurred_at?
Perché un nuovo tentativo ripete la consegna esattamente, con lo stesso id nel corpo e in X-EC-Delivery, e perché un evento ritentato può arrivare dopo uno più recente. Salva gli id già elaborati e salta i duplicati. Poi confronta occurred_at con l'ultimo stato registrato per quella connessione, oppure leggi GET /connections/{id} o GET /channels/{id} prima di agire su un evento che potrebbe essere obsoleto.
Cosa deve fare una piattaforma quando un numero si disconnette?
Agire in base al motivo. Dopo PRIMARY_INACTIVITY, chiedi al cliente di aprire l'app WhatsApp Business e inviagli una nuova sessione di connessione per lo stesso numero. Riconnetterlo nello stesso WhatsApp Business Account ne mantiene l'ID di connessione, ripristina la destinazione del tuo webhook e invia connection.connected; a quel punto rileggi le sue credenziali. connection.token_missing indica invece che Meta non ha emesso alcun token in quel passaggio. Meta invia l'account_update che sta dietro una disconnessione solo al callback dell'app, mai al tuo URL, quindi questo evento è il modo in cui la tua piattaforma ne viene a sapere.
Cosa deve fare una piattaforma quando un account social si disconnette?
Su channel.disconnected, una nuova sessione di connessione con lo stesso canale riautentica l'account, sotto lo stesso ID canale. channel.removed significa che l'accesso è stato revocato: il token viene dimenticato e la destinazione del webhook cancellata, quindi imposta di nuovo la destinazione se il cliente si riconnette. Un numero o un canale sospeso torna attivo riconnettendolo una volta che l'abbonamento è di nuovo attivo.
Errori comuni
- Trattare un nuovo tentativo come un nuovo evento. Ha lo stesso id nel corpo e in X-EC-Delivery, quindi registra gli id elaborati, altrimenti una sola disconnessione può avvisare un cliente due volte.
- Applicare gli eventi nell'ordine di arrivo. Un evento ritentato può arrivare dopo uno più recente, quindi confronta occurred_at o leggi la connessione prima di agire.
- Salvare di nuovo l'URL degli eventi per correggere un refuso senza aggiornare il backend. Il salvataggio genera un nuovo segreto di firma, e ogni consegna fallisce la verifica finché il tuo endpoint non lo usa.
- Eseguire il lavoro prima di rispondere. Un gestore che impiega più di 10 secondi conta come fallito e l'evento torna, quindi rispondi prima con 2xx ed elabora dopo.
easyCoexistence monitora 24 ore su 24 il numero WhatsApp e gli account social di ogni cliente e invia alla tua piattaforma un evento firmato quando uno si connette, si interrompe, viene rimosso o sospeso, con il motivo di Meta per un numero che si disconnette. Da US$ 9 a US$ 0,75 per connessione al mese, con un prezzo che scende man mano che aggiungi connessioni, e i primi 3 giorni di prova gratuita.
Domande frequenti
Cosa significa PRIMARY_INACTIVITY?
È il motivo di Meta per disconnettere un numero Coexistence la cui app WhatsApp Business non è stata usata sul dispositivo principale per circa 14 giorni. Una nuova sessione di connessione per quel cliente riconnette il numero.
Gli eventi di stato includono i messaggi?
No. Riguardano lo stato di una connessione. I messaggi di un numero vanno da Meta alla propria destinazione webhook, e i commenti e i messaggi diretti dei social alla destinazione di ciascun canale.
Dove imposto l'URL degli eventi?
Nella dashboard sotto Profilo, poi Developers, oppure con lo strumento MCP set_partner_events_url. Il segreto di firma viene mostrato una sola volta, e salvare di nuovo l'URL ne genera uno nuovo.
Posso ignorare gli eventi channel se gestisco solo i numeri?
Sì. Gli eventi channel.* hanno nomi propri e portano un oggetto channel invece di connection, quindi un ricevitore può ignorare qualsiasi evento il cui nome non inizia con connection.
Continua a leggere
Collega il tuo primo canale in due minuti.
Nessuna revisione delle piattaforme da aspettare. Collega WhatsApp, Instagram, TikTok o un altro canale, poi chiedi alla tua AI di pubblicare, rispondere o fare un report, e guardala al lavoro.
- 3 giorni gratis
- Disdici quando vuoi
- Solo API ufficiali
- Monitorato 24/7
Verificato il