Prijavite seZapočnite besplatno probno razdoblje
easyCoexistence Službeni API-ji

Kako saznati kada se veza klijenta s WhatsAppom ili društvenim mrežama prekine

easyCoexistence šalje potpisane statusne događaje kada se veza klijenta s brojem ili društvenim računom poveže, prekine, ukloni ili suspendira. WhatsApp broj šalje connection.connected, connection.disconnected s Metinim razlogom, connection.removed, connection.suspended ili connection.token_missing; društveni račun šalje odgovarajuće channel.* događaje, bez token_missing. Svaki događaj je JSON POST zahtjev potpisan zaglavljem X-EC-Signature i ponavlja se s rastućim razmacima oko 33 sata, dok vaš endpoint ne odgovori statusom 2xx.

~14 days

PRIMARY_INACTIVITY: Metin razlog kada primarni uređaj nije bio aktivan otprilike 14 dana, što isključuje Coexistence broj.

~30 days

COMPANION_INACTIVITY: Metin razlog kada pomoćni uređaj nije bio aktivan otprilike 30 dana.

account_update

Webhook koji javlja prekid veze. Meta ga uvijek šalje na zadani callback URL aplikacije, nikada na zamjensku adresu.

7 attempts

Koliko se često pokušava dostaviti statusni događaj nakon svakog odgovora različitog od 2xx, s razmacima od 1 minute do 24 sata, tijekom oko 33 sata.

5 minutes

Najstarija potpisana vremenska oznaka t koju endpoint smije prihvatiti za statusni događaj, uz usporedbu HMAC-a u stalnom vremenu.

Koji statusni događaji postoje?

Devet, u dvije skupine koje dijele jedan endpoint i jedan tajni ključ za potpisivanje. Brojevi koriste connection.*, a društveni računi channel.*, pa primatelj napisan za brojeve može preskočiti channel događaje po imenu. Endpoint postavite na nadzornoj ploči pod Profile, pa Developers, ili MCP alatom set_partner_events_url; tajni ključ za potpisivanje prikazuje se samo jednom, kada se URL spremi.

connection.connectedA number connected, came back after a drop, or got its customer token on a second run.
connection.disconnectedMeta dropped the link; reason carries Meta's code when known.
connection.removedRemoved with DELETE /connections/{id} or from the dashboard.
connection.suspendedYour subscription lapsed; reason names its state.
connection.token_missingConnected without a customer token: it receives, but cannot send yet.
channel.connectedA social account connected, one event per Page when a sign-in brings several.
channel.disconnectedThe network refused the token, or the owner withdrew access.
channel.removedRemoved with DELETE /channels/{id} or from the dashboard, or the owner removed the app on Meta.
channel.suspendedYour subscription lapsed.

Što sadrži događaj veze?

ID isporuke, UUID; naziv događaja; occurred_at u ISO 8601; te objekt connection s poljima id, external_ref, connect_session_id, phone, name, waba_id, phone_number_id, status i token_ready. Neki događaji dodaju polje na najvišoj razini: reason kod connection.disconnected i connection.suspended, detected_by s vrijednošću health_check kada je prekid otkrila periodična provjera koju provodi easyCoexistence, a ne Metin webhook, te connect_session_id kada je događaj nastao iz connect sesije.

connection.disconnected
{
  "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"
}

Što sadrži događaj kanala?

Isti omotač s objektom channel umjesto connection. Riječ je o prikazu GET /channels/{id}: id, channel za mrežu, external_ref, connect_session_id, name, username, external_id, status, token_ready, webhook_url, disconnected_reason, last_checked_at i created_at. Za kanale nema token_missing, jer prijava na društvenu mrežu uvijek daje vlastiti token klijenta, a channel.connected nastao iz connect sesije na najvišoj razini također nosi connect_session_id.

channel.disconnected
{
  "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"
  }
}

Što znače razlozi prekida?

reason kod connection.disconnected je kod koji je Meta upisala u disconnection_info svog account_update webhooka; Meta ga uključuje za brojeve i u aplikaciji WhatsApp Business i u Cloud API-ju. Null je kada Meta nije dala nijedan. Kodovi iz Metine reference:

  • PRIMARY_INACTIVITY: telefon na kojem radi aplikacija WhatsApp Business nije bio aktivan oko 14 dana, prema pravilu 14 dana. Nova connect sesija ponovno povezuje broj.
  • ACCOUNT_DISCONNECTED: račun je prekinut Metinom provedbom pravila ili od strane klijenta, koji je mogao ukloniti pristup ili obrisati račun.
  • COMPANION_INACTIVITY: pomoćni uređaj nije bio aktivan oko 30 dana.
  • BUSINESS_DOWNGRADE: broj je bio registriran u potrošačkoj aplikaciji WhatsApp.
  • CHANGE_NUMBER i USER_RE_REGISTERED: klijent je promijenio broj ili ga ponovno registrirao na novom uređaju.

Koja zaglavlja dolaze uz statusni događaj?

Pet, pri svakom pokušaju: Content-Type application/json, User-Agent easyCoexistence-webhooks/1, X-EC-Event s nazivom događaja, X-EC-Delivery s istim ID-em kao u tijelu i X-EC-Signature. Potpis glasi t=<unix>,v1=<hex>, gdje je v1 HMAC-SHA256 od t, točke i sirovog tijela, uz ključ za potpisivanje vašeg računa, koji počinje s whsec_. Svaki pokušaj potpisuje se iznova, pa ponovni pokušaj nosi novi t uz isto tijelo.

Python: verify, then handle each id once
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

Kako se neuspjele isporuke ponavljaju?

Prvi pokušaj šalje se u trenutku događaja. Odgovor različit od 2xx, nikakav odgovor unutar 10 sekundi, mrežna pogreška ili preusmjeravanje smatraju se neuspjehom, pa se događaj ponovno pokušava s rastućim razmacima, od 1 minute do 24 sata, ukupno sedam pokušaja tijekom oko 33 sata, prije nego što se odbaci. Isporuke idu samo na HTTPS adresu koja se razrješava u javnu IP adresu. Događaj koji se dogodi dok endpoint nije postavljen nikada se ne stavlja u red čekanja, a uklanjanje endpointa zaustavlja sve što je na čekanju.

Zašto obraditi svaki id jednom i provjeriti occurred_at?

Jer ponovni pokušaj ponavlja isporuku točno, s istim id-em u tijelu i u X-EC-Delivery, a ponovljeni događaj može stići nakon novijeg. Spremite id-eve koje ste obradili i preskačite ponavljanja. Zatim usporedite occurred_at s posljednjim stanjem koje ste zabilježili za tu vezu ili pročitajte GET /connections/{id} ili GET /channels/{id} prije nego što djelujete na događaj koji bi mogao biti zastario.

Što platforma treba učiniti kada broj prekine vezu?

Djelovati prema razlogu. Nakon PRIMARY_INACTIVITY zamolite klijenta da otvori aplikaciju WhatsApp Business i pošaljite mu novu connect sesiju za isti broj. Ponovno povezivanje u istom računu WhatsApp Business Account zadržava ID veze, vraća vaše odredište webhooka i šalje connection.connected, nakon čega ponovno čitate njegove vjerodajnice. connection.token_missing znači da Meta u tom pokušaju povezivanja nije izdala token. Meta account_update koji stoji iza prekida šalje samo na callback aplikacije, nikada na vaš URL, pa je ovaj događaj način na koji vaša platforma saznaje za njega.

Što platforma treba učiniti kada društveni račun prekine vezu?

Na channel.disconnected nova connect sesija s istim kanalom ponovno prijavljuje račun, pod istim ID-em kanala. channel.removed znači da je pristup nestao: token se zaboravlja, a odredište webhooka briše, pa ga ponovno postavite ako se klijent ponovno poveže. Suspendirani broj ili kanal vraća se ponovnim povezivanjem nakon što je vaša pretplata ponovno aktivna.

Uobičajene pogreške

  • Tretiranje ponovnog pokušaja kao novog događaja. Nosi isti id u tijelu i u X-EC-Delivery, pa bilježite obrađene ID-eve, inače jedan prekid može uzbuniti klijenta dvaput.
  • Primjena događaja redoslijedom dolaska. Ponovljeni događaj može stići nakon novijeg, pa usporedite occurred_at ili pročitajte vezu prije djelovanja.
  • Ponovno spremanje URL-a za događaje radi ispravljanja tipfelera bez ažuriranja backenda. Spremanje izdaje novi tajni ključ za potpisivanje, pa svaka isporuka ne prolazi provjeru dok vaš endpoint ne počne koristiti novi.
  • Obavljanje posla prije odgovora. Obrada koja traje duže od 10 sekundi smatra se neuspjehom i događaj se vraća, zato prvo odgovorite 2xx, a zatim obrađujte.
Radite ovo uz EasyCoexistence

easyCoexistence neprekidno prati WhatsApp broj i društvene račune svakog klijenta te šalje vašoj platformi potpisani događaj kada se veza uspostavi, prekine, ukloni ili suspendira, uz Metin razlog za broj koji se prekine. Od US$ 9 do US$ 0.75 po vezi mjesečno, uz pad cijene kako dodajete veze, s prvih 3 dana besplatno.

Često postavljana pitanja

Što znači PRIMARY_INACTIVITY?

To je Metin razlog za prekid Coexistence broja čija aplikacija WhatsApp Business nije bila korištena na primarnom uređaju oko 14 dana. Nova connect sesija za tog klijenta ponovno povezuje broj.

Uključuju li statusni događaji poruke?

Ne. Pokrivaju status veze. Poruke broja idu od Mete na njegovo vlastito odredište webhooka, a komentari i izravne poruke (DM) s društvenih mreža idu na odredište svakog kanala.

Gdje postavljam URL za događaje?

Na nadzornoj ploči pod Profile, pa Developers, ili MCP alatom set_partner_events_url. Tajni ključ za potpisivanje prikazuje se jednom, a ponovno spremanje URL-a izdaje novi.

Mogu li ignorirati događaje kanala ako obrađujem samo brojeve?

Da. Događaji channel.* imaju vlastite nazive i nose objekt channel umjesto connection, pa primatelj može preskočiti svaki događaj čiji naziv ne počinje s connection.

Nastavite čitati

Povežite svoj prvi kanal u dvije minute.

Bez čekanja na provjere platformi. Povežite WhatsApp, Instagram, TikTok ili drugi kanal, zatim zamolite svoju umjetnu inteligenciju da objavi, odgovori ili izradi izvješće i gledajte kako radi.

  • 3 dana besplatno
  • Otkažite bilo kada
  • Samo službeni API-ji
  • Nadzor 24/7

Provjereno na