Jak dowiedzieć się, że połączenie klienta z WhatsApp lub kontem społecznościowym zostało przerwane
easyCoexistence wysyła do Twojej platformy podpisane zdarzenia statusu, gdy połączenie klienta z WhatsApp lub kontem w mediach społecznościowych zostaje nawiązane, przerwane, usunięte lub zawieszone. Numer WhatsApp wysyła connection.connected, connection.disconnected z przyczyną Meta, connection.removed, connection.suspended albo connection.token_missing. Konto społecznościowe wysyła odpowiedniki channel.*, bez token_missing. Każde zdarzenie to żądanie POST w formacie JSON, podpisane nagłówkiem X-EC-Signature i ponawiane z rosnącymi przerwami przez około 33 godziny, aż Twój endpoint odpowie kodem 2xx.
PRIMARY_INACTIVITY: przyczyna Meta, gdy główne urządzenie było nieaktywne przez około 14 dni, co rozłącza numer Coexistence.
COMPANION_INACTIVITY: przyczyna Meta, gdy urządzenie towarzyszące było nieaktywne przez około 30 dni.
Webhook, który zgłasza rozłączenie. Meta zawsze wysyła go na domyślny callback URL aplikacji, nigdy na jego nadpisanie.
Jak często zdarzenie statusu jest ponawiane po każdej odpowiedzi innej niż 2xx, z przerwami od 1 minuty do 24 godzin, przez około 33 godziny.
Najstarszy podpisany znacznik czasu t, jaki endpoint powinien zaakceptować dla zdarzenia statusu, przy porównaniu HMAC w stałym czasie.
Jakie są zdarzenia statusu?
Dziewięć, w dwóch rodzinach, które współdzielą jeden endpoint i jeden sekret podpisu. Numery używają connection.*, a konta społecznościowe channel.*, więc odbiornik napisany dla numerów może pominąć zdarzenia channel po nazwie. Endpoint ustawiasz w panelu w sekcji „Profil”, a potem „Developers”, albo narzędziem MCP set_partner_events_url. Sekret podpisu jest pokazywany jednorazowo, po zapisaniu adresu URL.
Co zawiera zdarzenie połączenia?
Identyfikator dostarczenia, UUID; nazwę zdarzenia; occurred_at w formacie ISO 8601; oraz obiekt connection z polami id, external_ref, connect_session_id, phone, name, waba_id, phone_number_id, status i token_ready. Niektóre zdarzenia dodają pole najwyższego poziomu: reason w connection.disconnected i connection.suspended, detected_by ustawione na health_check, gdy cykliczna kontrola easyCoexistence wykryła przerwanie, a nie webhook Meta, oraz connect_session_id, gdy zdarzenie wywołała sesja połączenia.
{
"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"
}Co zawiera zdarzenie kanału?
Tę samą kopertę z obiektem channel zamiast connection. To widok GET /channels/{id}: id, channel dla sieci, external_ref, connect_session_id, name, username, external_id, status, token_ready, webhook_url, disconnected_reason, last_checked_at i created_at. Dla kanałów nie ma token_missing, ponieważ logowanie przez media społecznościowe zawsze daje token samego klienta. Zdarzenie channel.connected pochodzące z sesji połączenia niesie także connect_session_id na najwyższym poziomie.
{
"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"
}
}Co oznaczają przyczyny rozłączenia?
reason w connection.disconnected to kod, który Meta umieściła w disconnection_info swojego webhooka account_update. Meta dołącza go dla numerów zarówno w aplikacji WhatsApp Business, jak i w Cloud API. Jest null, gdy Meta nie podała żadnego. Kody z dokumentacji Meta:
PRIMARY_INACTIVITY: telefon z aplikacją WhatsApp Business był nieaktywny przez około 14 dni, czyli zgodnie z zasadą 14 dni. Nowa sesja połączenia ponownie łączy numer.ACCOUNT_DISCONNECTED: konto zostało rozłączone w ramach egzekwowania przez Meta albo przez klienta, który mógł usunąć dostęp lub konto.COMPANION_INACTIVITY: urządzenie towarzyszące było nieaktywne przez około 30 dni.BUSINESS_DOWNGRADE: numer został zarejestrowany w konsumenckiej aplikacji WhatsApp.CHANGE_NUMBERiUSER_RE_REGISTERED: klient zmienił numer albo zarejestrował go ponownie na nowym urządzeniu.
Jakie nagłówki towarzyszą zdarzeniu statusu?
Pięć, przy każdej próbie: Content-Type application/json, User-Agent easyCoexistence-webhooks/1, X-EC-Event z nazwą zdarzenia, X-EC-Delivery z tym samym identyfikatorem co treść oraz X-EC-Signature. Podpis ma postać t=<unix>,v1=<hex>, gdzie v1 to HMAC-SHA256 z t, kropki i surowej treści, kluczowany sekretem podpisu Twojego konta, który zaczyna się od whsec_. Każda próba jest podpisywana od nowa, więc ponowienie niesie nowe t nad tą samą treścią.
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 200Jak ponawiane są nieudane dostarczenia?
Pierwsza próba wychodzi w chwili zdarzenia. Odpowiedź inna niż 2xx, brak odpowiedzi w ciągu 10 sekund, błąd sieci lub przekierowanie liczą się jako niepowodzenie. Zdarzenie jest ponawiane z rosnącymi przerwami, od 1 minuty do 24 godzin, łącznie siedem prób przez około 33 godziny, po czym zostaje porzucone. Dostarczenia trafiają tylko na adres HTTPS, który rozwiązuje się do publicznego IP. Zdarzenie, które wystąpi, gdy endpoint nie jest ustawiony, nigdy nie trafia do kolejki, a usunięcie endpointu zatrzymuje wszystko, co czeka.
Dlaczego obsługiwać każde id tylko raz i sprawdzać occurred_at?
Ponowienie powtarza dostarczenie dokładnie, z tym samym id w treści i w X-EC-Delivery, a ponowione zdarzenie może dotrzeć po nowszym. Zapisuj więc przetworzone identyfikatory i pomijaj powtórki. Następnie porównaj occurred_at z ostatnim zapisanym stanem dla tego połączenia albo odczytaj GET /connections/{id} lub GET /channels/{id}, zanim zadziałasz na zdarzenie, które może być nieaktualne.
Co powinna zrobić platforma, gdy numer się rozłączy?
Działaj zgodnie z przyczyną. Po PRIMARY_INACTIVITY poproś klienta o otwarcie aplikacji WhatsApp Business i wyślij mu nową sesję połączenia dla tego samego numeru. Ponowne połączenie na tym samym koncie WhatsApp Business Account zachowuje identyfikator połączenia, przywraca cel webhooka i wysyła connection.connected, po czym dane uwierzytelniające odczytujesz ponownie. connection.token_missing oznacza natomiast, że Meta nie wydała tokenu w tym przebiegu. Meta wysyła account_update stojący za rozłączeniem wyłącznie na callback samej aplikacji, nigdy na Twój URL, dlatego to zdarzenie jest sposobem, w jaki Twoja platforma się o nim dowiaduje.
Co powinna zrobić platforma, gdy konto społecznościowe się rozłączy?
Po channel.disconnected nowa sesja połączenia z tym samym kanałem loguje konto ponownie, pod tym samym identyfikatorem kanału. channel.removed oznacza, że dostęp zniknął: token zostaje zapomniany, a cel webhooka wyczyszczony, więc ustaw go ponownie, jeśli klient połączy się na nowo. Zawieszony numer lub kanał wraca po ponownym połączeniu, gdy Twoja subskrypcja znów jest aktywna.
Typowe błędy
- Traktowanie ponowienia jako nowego zdarzenia. Ma ten sam id w treści i w X-EC-Delivery, więc zapisuj przetworzone identyfikatory, bo jedno rozłączenie może zaalarmować klienta dwukrotnie.
- Stosowanie zdarzeń w kolejności przybycia. Ponowione zdarzenie może dotrzeć po nowszym, więc porównuj occurred_at albo odczytaj połączenie przed działaniem.
- Ponowne zapisywanie URL zdarzeń, żeby poprawić literówkę, bez aktualizacji backendu. Zapis wystawia nowy sekret podpisu i każde dostarczenie nie przechodzi weryfikacji, dopóki Twój endpoint go nie używa.
- Wykonywanie pracy przed odpowiedzią. Handler, który trwa dłużej niż 10 sekund, liczy się jako nieudany, a zdarzenie wraca, dlatego najpierw odpowiedz 2xx, a potem przetwarzaj.
easyCoexistence obserwuje numer WhatsApp i konta społecznościowe każdego klienta przez całą dobę i wysyła Twojej platformie podpisane zdarzenie, gdy połączenie się nawiąże, rozłączy, zostanie usunięte lub zawieszone, z przyczyną Meta dla rozłączonego numeru. Od US$ 9 do US$ 0.75 za połączenie miesięcznie, spadając wraz z dodawaniem połączeń, z pierwszymi 3 dniami za darmo.
Najczęściej zadawane pytania
Co oznacza PRIMARY_INACTIVITY?
To przyczyna Meta, dla której rozłącza się numer Coexistence, którego aplikacja WhatsApp Business była nieużywana na głównym urządzeniu przez około 14 dni. Nowa sesja połączenia dla tego klienta ponownie łączy numer.
Czy zdarzenia statusu zawierają wiadomości?
Nie. Dotyczą statusu połączenia. Wiadomości z numeru idą z Meta na jego własny cel webhooka, a komentarze i wiadomości prywatne z mediów społecznościowych na cel każdego kanału.
Gdzie ustawiam URL zdarzeń?
W panelu w sekcji „Profil”, a potem „Developers”, albo narzędziem MCP set_partner_events_url. Sekret podpisu jest pokazywany jednorazowo, a ponowny zapis URL wystawia nowy.
Czy mogę ignorować zdarzenia kanałów, jeśli obsługuję tylko numery?
Tak. Zdarzenia channel.* mają własne nazwy i niosą obiekt channel zamiast connection, więc odbiornik może pominąć każde zdarzenie, którego nazwa nie zaczyna się od connection.
Czytaj dalej
Połącz pierwszy kanał w dwie minuty.
Bez czekania na weryfikację przez platformy. Połącz WhatsApp, Instagram, TikTok lub inny kanał, a potem poproś swoją AI o opublikowanie posta, odpowiedź lub raport i zobacz, jak działa.
- 3 dni za darmo
- Rezygnacja w każdej chwili
- Tylko oficjalne API
- Monitorowanie 24/7
Zweryfikowano w