Hoe je weet wanneer de WhatsApp- of socialmediaverbinding van een klant wegvalt
easyCoexistence stuurt een door het platform ondertekend statusevent wanneer de verbinding van een klant tot stand komt, wegvalt, wordt verwijderd of wordt opgeschort. Een WhatsApp-nummer stuurt connection.connected, connection.disconnected met de reden van Meta, connection.removed, connection.suspended of connection.token_missing; een socialmediaaccount stuurt de bijbehorende channel.*-events, zonder token_missing. Elk event is een JSON-POST, ondertekend met X-EC-Signature en opnieuw verstuurd met oplopende wachttijd gedurende ongeveer 33 uur, totdat je endpoint met 2xx antwoordt.
PRIMARY_INACTIVITY: de reden van Meta wanneer het primaire apparaat ongeveer 14 dagen inactief was, waardoor een Coexistence-nummer wordt losgekoppeld.
COMPANION_INACTIVITY: de reden van Meta wanneer een companion-apparaat ongeveer 30 dagen inactief was.
De webhook die een loskoppeling meldt. Meta stuurt die altijd naar de standaard callback-URL van de app, nooit naar een eigen, afwijkende URL.
Hoe vaak een statusevent opnieuw wordt geprobeerd na elk antwoord buiten 2xx, met tussenpozen van 1 minuut tot 24 uur, gedurende ongeveer 33 uur.
De oudste ondertekende tijdstempel t die een endpoint bij een statusevent mag accepteren, waarbij de HMAC in constante tijd wordt vergeleken.
Welke statusevents zijn er?
Negen, in twee families die één endpoint en één ondertekeningsgeheim delen. Nummers gebruiken connection.* en socialmediaaccounts gebruiken channel.*, zodat een ontvanger die voor nummers is geschreven kanaalevents op naam kan overslaan. Stel het endpoint in het dashboard in onder Profiel, dan Developers, of met de MCP-tool set_partner_events_url; het ondertekeningsgeheim wordt één keer getoond, wanneer de URL wordt opgeslagen.
Wat bevat een verbindingsevent?
De id van de levering, een UUID; de naam van het event; occurred_at in ISO 8601; en een connection-object met id, external_ref, connect_session_id, phone, name, waba_id, phone_number_id, status en token_ready. Sommige events voegen een veld op het hoogste niveau toe: reason bij connection.disconnected en connection.suspended, detected_by met de waarde health_check wanneer de eigen periodieke controle van easyCoexistence het wegvallen vond en niet de webhook van Meta, en connect_session_id wanneer een connect-sessie het event veroorzaakte.
{
"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"
}Wat bevat een kanaalevent?
Dezelfde envelop, met een channel-object in plaats van connection. Het is de weergave van GET /channels/{id}: id, channel voor het netwerk, external_ref, connect_session_id, name, username, external_id, status, token_ready, webhook_url, disconnected_reason, last_checked_at en created_at. Voor kanalen is er geen token_missing, omdat een aanmelding via sociale media altijd het eigen token van de klant oplevert. Een channel.connected dat uit een connect-sessie komt, bevat ook connect_session_id op het hoogste niveau.
{
"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"
}
}Wat betekenen de redenen voor loskoppeling?
reason bij connection.disconnected is de code die Meta plaatste in de disconnection_info van zijn account_update-webhook, die Meta meestuurt voor nummers in zowel de WhatsApp Business-app als de Cloud API. Het is null wanneer Meta geen reden gaf. De codes uit de referentie van Meta:
PRIMARY_INACTIVITY: de telefoon met de WhatsApp Business-app was ongeveer 14 dagen inactief, de 14-dagenregel. Een nieuwe connect-sessie verbindt het nummer opnieuw.ACCOUNT_DISCONNECTED: het account is losgekoppeld via handhaving door Meta of door de klant, die toegang kan hebben ingetrokken of het account kan hebben verwijderd.COMPANION_INACTIVITY: een companion-apparaat was ongeveer 30 dagen inactief.BUSINESS_DOWNGRADE: het nummer was geregistreerd bij de consumenten-WhatsApp-app.CHANGE_NUMBERenUSER_RE_REGISTERED: de klant heeft het nummer gewijzigd, of het opnieuw geregistreerd op een nieuw apparaat.
Welke headers komen bij een statusevent mee?
Vijf, bij elke poging: Content-Type application/json, User-Agent easyCoexistence-webhooks/1, X-EC-Event met de naam van het event, X-EC-Delivery met dezelfde id als de body, en X-EC-Signature. De handtekening luidt t=<unix>,v1=<hex>, waarbij v1 de HMAC-SHA256 is van t, een punt en de ruwe body, gesleuteld met het ondertekeningsgeheim van je account, dat begint met whsec_. Elke poging wordt opnieuw ondertekend, dus een herhaling bevat een nieuwe t over dezelfde body.
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 200Hoe worden mislukte leveringen opnieuw verstuurd?
De eerste poging gaat uit op het moment dat het event plaatsvindt. Een antwoord buiten 2xx, geen antwoord binnen 10 seconden, een netwerkfout of een redirect telt als mislukking. Het event wordt dan opnieuw geprobeerd met oplopende tussenpozen, van 1 minuut tot 24 uur: zeven pogingen in totaal, gedurende ongeveer 33 uur, waarna het wordt weggegooid. Leveringen gaan alleen naar een HTTPS-adres dat naar een publiek IP-adres verwijst. Een event dat plaatsvindt terwijl geen endpoint is ingesteld, wordt nooit in de wachtrij gezet, en het verwijderen van het endpoint stopt alles wat nog in behandeling is.
Waarom elke id maar één keer verwerken en occurred_at controleren?
Omdat een herhaling de levering exact herhaalt, met dezelfde id in de body en in X-EC-Delivery, en omdat een opnieuw verstuurd event later kan aankomen dan een nieuwer event. Sla de id's op die je hebt verwerkt en sla herhalingen over. Vergelijk daarna occurred_at met de laatste status die je voor die verbinding hebt vastgelegd, of lees GET /connections/{id} of GET /channels/{id} voordat je handelt op een event dat mogelijk verouderd is.
Wat moet een platform doen wanneer een nummer wegvalt?
Handel op basis van de reden. Vraag de klant na PRIMARY_INACTIVITY de WhatsApp Business-app te openen en stuur een nieuwe connect-sessie voor hetzelfde nummer. Opnieuw verbinden op hetzelfde WhatsApp Business-account behoudt de connection-id, zet je webhook-bestemming terug en stuurt connection.connected, waarna je de inloggegevens opnieuw uitleest. connection.token_missing betekent daarentegen dat Meta bij die run geen token heeft uitgegeven. Meta stuurt de account_update bij een loskoppeling alleen naar de eigen callback van de app, nooit naar jouw URL, dus dit event is de manier waarop jouw platform ervan hoort.
Wat moet een platform doen wanneer een socialmediaaccount wegvalt?
Bij channel.disconnected meldt een nieuwe connect-sessie met hetzelfde kanaal het account opnieuw aan, onder dezelfde channel-id. channel.removed betekent dat de toegang weg is: het token wordt vergeten en eventuele webhook-bestemmingen worden gewist, dus stel de bestemming opnieuw in als de klant opnieuw verbindt. Een opgeschort nummer of kanaal komt terug wanneer je het opnieuw verbindt, zodra je abonnement weer actief is.
Veelgemaakte fouten
- Een herhaling als nieuw event behandelen. Die heeft dezelfde id in de body en in X-EC-Delivery, dus registreer verwerkte id's, anders kan één loskoppeling een klant twee keer waarschuwen.
- Events toepassen in volgorde van aankomst. Een opnieuw verstuurd event kan na een nieuwer event binnenkomen, dus vergelijk occurred_at of lees de verbinding voordat je handelt.
- De events-URL opnieuw opslaan om een typfout te herstellen, zonder de backend bij te werken. Opslaan geeft een nieuw ondertekeningsgeheim uit, en elke levering faalt de verificatie totdat je endpoint het gebruikt.
- Het werk uitvoeren voordat je antwoordt. Een handler die langer dan 10 seconden duurt telt als mislukt en het event komt terug, dus antwoord eerst met 2xx en verwerk daarna.
easyCoexistence houdt de WhatsApp-nummers en socialmediaaccounts van elke klant de klok rond in de gaten en stuurt je platform een ondertekend event wanneer er één tot stand komt, wegvalt, wordt verwijderd of wordt opgeschort, met de reden van Meta voor een nummer dat wegvalt. US$ 9 tot US$ 0,75 per verbinding per maand, dalend naarmate je verbindingen toevoegt, met een gratis proefperiode van 3 dagen.
Veelgestelde vragen
Wat betekent PRIMARY_INACTIVITY?
Dat is de reden van Meta om een Coexistence-nummer los te koppelen waarvan de WhatsApp Business-app op het primaire apparaat ongeveer 14 dagen niet is gebruikt. Een nieuwe connect-sessie voor die klant verbindt het nummer opnieuw.
Bevatten statusevents berichten?
Nee. Ze gaan over de status van een verbinding. Berichten van een nummer gaan van Meta naar de eigen webhook-bestemming, en reacties en DM's op sociale media naar de bestemming van elk kanaal.
Waar stel ik de events-URL in?
In het dashboard onder Profiel, dan Developers, of met de MCP-tool set_partner_events_url. Het ondertekeningsgeheim wordt één keer getoond, en het opnieuw opslaan van de URL geeft een nieuw geheim uit.
Kan ik kanaalevents negeren als ik alleen nummers beheer?
Ja. channel.*-events hebben eigen namen en bevatten een channel-object in plaats van connection, dus een ontvanger kan elk event overslaan waarvan de naam niet met connection begint.
Lees verder
Koppel je eerste kanaal in twee minuten.
Geen platformbeoordelingen om op te wachten. Verbind WhatsApp, Instagram, TikTok of een ander kanaal, vraag je AI om te posten, te reageren of een rapport te maken, en zie het aan het werk.
- 3 dagen gratis
- Op elk moment opzegbaar
- Alleen officiële API's
- 24/7 bewaakt
Geverifieerd op