Conectați-văÎncepeți perioada de probă gratuită
easyCoexistence API-uri oficiale

Cum aflați când se întrerupe conexiunea WhatsApp sau socială a unui client

easyCoexistence trimite platformei dumneavoastră evenimente de status semnate când conexiunea unui client se conectează, se întrerupe, este eliminată sau suspendată. Un număr WhatsApp trimite connection.connected, connection.disconnected cu motivul Meta, connection.removed, connection.suspended sau connection.token_missing; un cont social trimite echivalentele channel.*, fără token_missing. Fiecare este un POST JSON semnat cu X-EC-Signature și reîncercat cu întârziere timp de circa 33 de ore, până când endpoint-ul dumneavoastră răspunde cu 2xx.

~14 days

PRIMARY_INACTIVITY: motivul Meta când dispozitivul principal a fost inactiv timp de aproximativ 14 zile, deconectând un număr Coexistence.

~30 days

COMPANION_INACTIVITY: motivul Meta când un dispozitiv companion a fost inactiv timp de aproximativ 30 de zile.

account_update

Webhook-ul care raportează o deconectare. Meta îl trimite întotdeauna la URL-ul de callback implicit al aplicației, niciodată la o suprascriere.

7 attempts

Cât de des se reîncearcă un eveniment de status după orice răspuns în afara 2xx, cu intervale de la 1 minut la 24 de ore, timp de circa 33 de ore.

5 minutes

Marcajul de timp t cel mai vechi pe care un endpoint trebuie să îl accepte pentru un eveniment de status, comparând HMAC-ul în timp constant.

Care sunt evenimentele de status?

Nouă, în două familii care împart același endpoint și același secret de semnare. Numerele folosesc connection.*, iar conturile sociale channel.*, așa că un receptor scris pentru numere poate ignora evenimentele channel după nume. Setați endpoint-ul în dashboard, la Profil, apoi Dezvoltatori, sau cu instrumentul MCP set_partner_events_url; secretul de semnare se afișează o singură dată, când URL-ul este salvat.

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.

Ce conține un eveniment de conexiune?

ID-ul livrării, un UUID; numele evenimentului; occurred_at în ISO 8601; și un obiect connection cu id, external_ref, connect_session_id, phone, name, waba_id, phone_number_id, status și token_ready. Unele evenimente adaugă un câmp de nivel superior: reason la connection.disconnected și connection.suspended, detected_by setat la health_check când verificarea periodică proprie a easyCoexistence a găsit întreruperea, în loc de webhook-ul Meta, și connect_session_id când o sesiune de conectare a produs evenimentul.

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"
}

Ce conține un eveniment de canal?

Același înveliș, cu un obiect channel în locul lui connection. Este vizualizarea GET /channels/{id}: id, channel pentru rețea, external_ref, connect_session_id, name, username, external_id, status, token_ready, webhook_url, disconnected_reason, last_checked_at și created_at. Pentru canale nu există token_missing, deoarece o autentificare socială aduce întotdeauna token-ul propriu al clientului, iar un channel.connected care vine dintr-o sesiune de conectare poartă și el connect_session_id la nivel superior.

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"
  }
}

Ce înseamnă motivele de deconectare?

reason la connection.disconnected este codul pe care Meta l-a pus în disconnection_info din webhook-ul său account_update, pe care Meta îl include pentru numerele din aplicația WhatsApp Business și din Cloud API. Este null când Meta nu a dat niciunul. Codurile din referința Meta:

  • PRIMARY_INACTIVITY: telefonul cu aplicația WhatsApp Business a fost inactiv timp de circa 14 zile, regula celor 14 zile. O sesiune de conectare nouă reconectează numărul.
  • ACCOUNT_DISCONNECTED: contul a fost deconectat prin măsurile de aplicare ale Meta sau de client, care poate să fi retras accesul sau să fi șters contul.
  • COMPANION_INACTIVITY: un dispozitiv companion a fost inactiv timp de circa 30 de zile.
  • BUSINESS_DOWNGRADE: numărul a fost înregistrat în aplicația WhatsApp pentru consumatori.
  • CHANGE_NUMBER și USER_RE_REGISTERED: clientul a schimbat numărul sau l-a înregistrat din nou pe un dispozitiv nou.

Ce anteturi vin cu un eveniment de status?

Cinci, la fiecare încercare: Content-Type application/json, User-Agent easyCoexistence-webhooks/1, X-EC-Event cu numele evenimentului, X-EC-Delivery cu același id ca în corp și X-EC-Signature. Semnătura arată astfel t=<unix>,v1=<hex>, unde v1 este HMAC-SHA256 calculat peste t, un punct și corpul brut, cheia fiind secretul de semnare al contului dumneavoastră, care începe cu whsec_. Fiecare încercare este semnată din nou, astfel că o reîncercare poartă un t nou peste același corp.

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

Cum sunt reîncercate livrările eșuate?

Prima încercare pleacă în momentul în care se întâmplă evenimentul. Un răspuns în afara 2xx, lipsa unui răspuns în 10 secunde, o eroare de rețea sau o redirecționare contează drept eșec, iar evenimentul este reîncercat cu intervale tot mai mari, de la 1 minut la 24 de ore, șapte încercări în total, timp de circa 33 de ore, după care este eliminat. Livrările merg doar către o adresă HTTPS care se rezolvă într-un IP public. Un eveniment care se produce cât timp nu este setat niciun endpoint nu este pus în coadă niciodată, iar eliminarea endpoint-ului oprește tot ce este în așteptare.

De ce să tratăm fiecare id o singură dată și să verificăm occurred_at?

Pentru că o reîncercare repetă livrarea exact, cu același id în corp și în X-EC-Delivery, și pentru că un eveniment reîncercat poate sosi după unul mai nou. Stocați id-urile procesate și săriți peste repetări. Apoi comparați occurred_at cu ultima stare înregistrată pentru acea conexiune sau citiți GET /connections/{id} ori GET /channels/{id} înainte de a acționa asupra unui eveniment care ar putea fi depășit.

Ce ar trebui să facă o platformă când se întrerupe un număr?

Acționați în funcție de motiv. După PRIMARY_INACTIVITY, cereți clientului să deschidă aplicația WhatsApp Business și trimiteți-i o sesiune de conectare nouă pentru același număr. Reconectarea pe același cont WhatsApp Business păstrează ID-ul conexiunii, readuce destinația webhook-ului dumneavoastră și trimite connection.connected, după care citiți din nou credențialele; connection.token_missing înseamnă în schimb că Meta nu a emis niciun token în acea rulare. Meta trimite account_update din spatele unei întreruperi doar către callback-ul propriu al aplicației, niciodată către URL-ul dumneavoastră, așa că acest eveniment este modul în care platforma dumneavoastră află despre ea.

Ce ar trebui să facă o platformă când se întrerupe un cont social?

La channel.disconnected, o sesiune de conectare nouă pentru același canal autentifică din nou contul, sub același ID de canal. channel.removed înseamnă că accesul a dispărut: token-ul este uitat, iar destinația webhook-ului este ștearsă, așa că setați destinația din nou dacă clientul se reconectează. Un număr sau canal suspendat revine prin reconectare, odată ce abonamentul dumneavoastră este din nou activ.

Greșeli frecvente

  • Tratarea unei reîncercări ca pe un eveniment nou. Ea poartă același id în corp și în X-EC-Delivery, așa că înregistrați id-urile procesate, altfel o singură întrerupere poate alerta un client de două ori.
  • Aplicarea evenimentelor în ordinea sosirii. Un eveniment reîncercat poate ajunge după unul mai nou, așa că comparați occurred_at sau citiți conexiunea înainte de a acționa.
  • Salvarea din nou a URL-ului pentru evenimente ca să corectați o greșeală de scriere, fără să actualizați backend-ul. Salvarea emite un nou secret de semnare, iar fiecare livrare eșuează verificarea până când endpoint-ul dumneavoastră îl folosește.
  • Lucrul efectiv înainte de a răspunde. Un handler care durează mai mult de 10 secunde este considerat eșuat și evenimentul revine, așa că răspundeți mai întâi cu 2xx și procesați după aceea.
Faceți acest lucru cu EasyCoexistence

easyCoexistence urmărește non-stop numărul WhatsApp și conturile sociale ale fiecărui client și trimite platformei dumneavoastră un eveniment semnat când unul se conectează, se întrerupe, este eliminat sau suspendat, cu motivul Meta pentru un număr care se întrerupe. De la US$ 9 la US$ 0,75 pe conexiune pe lună, scăzând pe măsură ce adăugați conexiuni, cu primele 3 zile gratuite.

Întrebări frecvente

Ce înseamnă PRIMARY_INACTIVITY?

Este motivul Meta pentru deconectarea unui număr Coexistence al cărui aplicație WhatsApp Business nu a fost folosită pe dispozitivul principal timp de circa 14 zile. O sesiune de conectare nouă pentru acel client reconectează numărul.

Evenimentele de status includ mesajele?

Nu. Ele acoperă starea unei conexiuni. Mesajele unui număr merg de la Meta la propria destinație webhook, iar comentariile și DM-urile de pe rețelele sociale merg la destinația fiecărui canal.

Unde setez URL-ul pentru evenimente?

În dashboard, la Profil, apoi Dezvoltatori, sau cu instrumentul MCP set_partner_events_url. Secretul de semnare se afișează o singură dată, iar salvarea URL-ului din nou emite unul nou.

Pot ignora evenimentele de canal dacă gestionez doar numere?

Da. Evenimentele channel.* au nume proprii și poartă un obiect channel în locul lui connection, așa că un receptor poate sări peste orice eveniment al cărui nume nu începe cu connection.

Continuați să citiți

Conectați primul canal în două minute.

Fără recenzii de platformă de așteptat. Conectați WhatsApp, Instagram, TikTok sau alt canal, apoi cereți AI-ului să publice, să răspundă sau să raporteze și urmăriți-l cum lucrează.

  • 3 zile gratuit
  • Anulați oricând
  • Doar API-uri oficiale
  • Monitorizat 24/7

Verificat la