Kirjaudu sisäänAloita ilmainen kokeilu
easyCoexistence Viralliset API:t

Miten tiedät, kun asiakkaan WhatsApp- tai sosiaalisen median yhteys katkeaa

easyCoexistence lähettää alustallesi allekirjoitettuja tilatapahtumia, kun asiakkaan yhteys muodostuu, katkeaa, poistetaan tai keskeytetään. WhatsApp-numero lähettää tapahtumat connection.connected, connection.disconnected Metan antamalla syyllä, connection.removed, connection.suspended tai connection.token_missing. Sosiaalisen median tili lähettää vastaavat channel.*-tapahtumat ilman token_missingia. Jokainen on JSON-POST-pyyntö, joka on allekirjoitettu X-EC-Signature-otsakkeella ja jota yritetään uudelleen viiveellä noin 33 tunnin ajan, kunnes endpointisi vastaa 2xx-koodilla.

~14 days

PRIMARY_INACTIVITY: Metan syy, kun ensisijainen laite on ollut käyttämättä noin 14 päivää, jolloin Coexistence-numero katkeaa.

~30 days

COMPANION_INACTIVITY: Metan syy, kun toissijainen laite on ollut käyttämättä noin 30 päivää.

account_update

Webhook, joka raportoi yhteyden katkeamisesta. Meta lähettää sen aina sovelluksen oletustakaisinkutsun URL-osoitteeseen, ei koskaan ohitettuun osoitteeseen.

7 attempts

Kuinka usein tilatapahtumaa yritetään uudelleen, kun vastaus on jokin muu kuin 2xx. Välit ovat 1 minuutista 24 tuntiin, yhteensä noin 33 tunnin ajan.

5 minutes

Vanhin allekirjoitettu aikaleima t, jonka endpointin tulisi hyväksyä tilatapahtumalle, ja HMAC vertaillaan vakioajassa.

Mitkä tilatapahtumat ovat olemassa?

Yhdeksän, kahdessa perheessä, jotka jakavat yhden endpointin ja yhden allekirjoitusavaimen. Numerot käyttävät connection.*-tapahtumia ja sosiaalisen median tilit channel.*-tapahtumia, joten numeroille kirjoitettu vastaanotin voi ohittaa channel-tapahtumat nimeltä. Aseta endpoint hallintapaneelissa kohdassa Profiili, sitten Kehittäjät, tai MCP-työkalulla set_partner_events_url. Allekirjoitusavain näytetään kerran, kun URL tallennetaan.

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.

Mitä yhteystapahtuma sisältää?

Toimituksen id:n, UUID:n, tapahtuman nimen, occurred_at-aikaleiman ISO 8601 -muodossa ja connection-objektin, jossa ovat id, external_ref, connect_session_id, phone, name, waba_id, phone_number_id, status ja token_ready. Osa tapahtumista lisää ylätason kentän: reason kentässä connection.disconnected ja connection.suspended, detected_by-kentän arvona health_check, kun easyCoexistencen oma säännöllinen tarkistus löysi katkeamisen Metan webhookin sijaan, ja connect_session_id, kun connect-istunto tuotti tapahtuman.

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

Mitä kanavatapahtuma sisältää?

Saman kirjekuoren, jossa connection-objektin sijasta on channel-objekti. Se vastaa GET /channels/{id} -näkymää: id, channel (verkosto), external_ref, connect_session_id, name, username, external_id, status, token_ready, webhook_url, disconnected_reason, last_checked_at ja created_at. Kanavilla ei ole token_missingia, koska sosiaalisen median kirjautuminen tuottaa aina asiakkaan oman tokenin. Connect-istunnosta tullut channel.connected-tapahtuma sisältää myös connect_session_id-kentän ylätasolla.

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

Mitä katkeamisen syyt tarkoittavat?

reason kentässä connection.disconnected on koodi, jonka Meta asetti account_update-webhookinsa disconnection_info-kenttään. Meta sisältää sen numeroille sekä WhatsApp Business -sovelluksessa että Cloud API:ssa. Kenttä on null, kun Meta ei antanut koodia. Metan viitteen koodit:

  • PRIMARY_INACTIVITY: WhatsApp Business -sovellusta käyttävä puhelin on ollut käyttämättä noin 14 päivää, eli 14 päivän sääntö. Uusi connect-istunto yhdistää numeron uudelleen.
  • ACCOUNT_DISCONNECTED: tili katkesi Metan valvonnan kautta tai asiakkaan toimesta, joka on voinut poistaa käyttöoikeuden tai tilin.
  • COMPANION_INACTIVITY: toissijainen laite on ollut käyttämättä noin 30 päivää.
  • BUSINESS_DOWNGRADE: numero oli rekisteröity kuluttajille tarkoitettuun WhatsApp-sovellukseen.
  • CHANGE_NUMBER ja USER_RE_REGISTERED: asiakas vaihtoi numeron tai rekisteröi sen uudelleen uudella laitteella.

Mitä otsakkeita tilatapahtuman mukana tulee?

Viisi jokaisella yrityksellä: Content-Type application/json, User-Agent easyCoexistence-webhooks/1, X-EC-Event tapahtuman nimen kanssa, X-EC-Delivery samalla id:llä kuin rungossa ja X-EC-Signature. Allekirjoitus on muotoa t=<unix>,v1=<hex>, jossa v1 on HMAC-SHA256 merkkijonosta t, piste ja raakarunko, avaimena tilisi allekirjoitusavain, joka alkaa whsec_. Jokainen yritys allekirjoitetaan uudelleen, joten uudelleenyritys kantaa uutta t-arvoa samaan runkoon.

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

Miten epäonnistuneet toimitukset yritetään uudelleen?

Ensimmäinen yritys lähtee heti, kun tapahtuma tapahtuu. Vastaus muu kuin 2xx, ei vastausta 10 sekunnin sisällä, verkkovirhe tai uudelleenohjaus lasketaan epäonnistumiseksi. Tapahtumaa yritetään uudelleen kasvavilla väleillä, 1 minuutista 24 tuntiin, seitsemän yritystä yhteensä noin 33 tunnin ajan, ennen kuin se hylätään. Toimitukset menevät vain HTTPS-osoitteeseen, joka ratkeaa julkiseksi IP-osoitteeksi. Tapahtumaa, joka tapahtuu ajanhetkellä, jolloin endpointia ei ole asetettu, ei koskaan laiteta jonoon, ja endpointin poistaminen pysäyttää kaikki odottavat yritykset.

Miksi käsitellä jokainen id kerran ja tarkistaa occurred_at?

Koska uudelleenyritys toistaa toimituksen täsmälleen, samalla id:llä rungossa ja X-EC-Deliveryssä, ja koska uudelleen yritetty tapahtuma voi saapua uudemman tapahtuman jälkeen. Tallenna käsitellyt id:t ja ohita toistot. Vertaa sitten occurred_at-aikaa yhteydelle viimeksi tallennettuun tilaan, tai lue GET /connections/{id} tai GET /channels/{id} ennen kuin toimit tapahtuman perusteella, joka voi olla vanhentunut.

Mitä alustan pitäisi tehdä, kun numero katkeaa?

Toimi syyn mukaan. PRIMARY_INACTIVITYn jälkeen pyydä asiakasta avaamaan WhatsApp Business -sovellus ja lähetä hänelle uusi connect-istunto samalle numerolle. Yhdistäminen uudelleen samalle WhatsApp Business -tilille säilyttää yhteyden id:n, palauttaa webhook-kohteen ja lähettää connection.connected-tapahtuman, jonka jälkeen luet tunnistetiedot uudelleen. connection.token_missing tarkoittaa sen sijaan, ettei Meta antanut tokenia tällä kerralla. Meta lähettää katkeamisen taustalla olevan account_update-tapahtuman vain sovelluksen omaan callbackiin, ei alustasi URL-osoitteeseen, joten tämä tapahtuma on se, miten alustasi saa siitä tiedon.

Mitä alustan pitäisi tehdä, kun sosiaalisen median tili katkeaa?

channel.disconnected-tapahtuman jälkeen uusi connect-istunto samalle kanavalle kirjaa tilin uudelleen sisään samalla channel-tunnuksella. channel.removed tarkoittaa, että pääsy on poistunut: token unohdetaan ja webhook-kohde tyhjennetään, joten aseta kohde uudelleen, jos asiakas yhdistää tilin uudelleen. Keskeytetty numero tai kanava palaa käyttöön, kun yhdistät sen uudelleen tilauksen ollessa jälleen aktiivinen.

Yleiset virheet

  • Uudelleenyrityksen käsittely uutena tapahtumana. Se kantaa samaa id:tä rungossa ja X-EC-Deliveryssä, joten tallenna käsitellyt id:t, muuten yksi katkeaminen voi hälyttää asiakkaan kahdesti.
  • Tapahtumien käsittely saapumisjärjestyksessä. Uudelleen yritetty tapahtuma voi osua uudemman jälkeen, joten vertaa occurred_at-aikaa tai lue yhteys ennen toimintaa.
  • Endpoint-URL:n tallentaminen uudelleen kirjoitusvirheen korjaamiseksi tekemättä backend-muutosta. Tallennus antaa uuden allekirjoitusavaimen, ja jokainen toimitus epäonnistuu todennuksessa, kunnes endpointisi käyttää sitä.
  • Työn tekeminen ennen vastaamista. Käsittelijä, joka vie yli 10 sekuntia, lasketaan epäonnistuneeksi ja tapahtuma palaa, joten vastaa ensin 2xx ja käsittele sen jälkeen.
Näin teet tämän EasyCoexistencen avulla

easyCoexistence valvoo jokaisen asiakkaan WhatsApp-numeroa ja sosiaalisen median tilejä ympäri vuorokauden ja lähettää alustallesi allekirjoitetun tapahtuman, kun yhteys muodostuu, katkeaa, poistetaan tai keskeytetään, Metan syy mukana numeron katketessa. US$ 9:stä US$ 0,75:een yhteydeltä kuukaudessa, hinnan laskiessa yhteyksiä lisättäessä, ensimmäiset 3 päivää ilmaiseksi.

Usein kysytyt kysymykset

Mitä PRIMARY_INACTIVITY tarkoittaa?

Se on Metan syy Coexistence-numeron katkaisemiselle, kun sen WhatsApp Business -sovellusta ei ole käytetty ensisijaisella laitteella noin 14 päivään. Uusi connect-istunto kyseiselle asiakkaalle yhdistää numeron uudelleen.

Sisältävätkö tilatapahtumat viestejä?

Eivät. Ne kattavat yhteyden tilan. Numeron viestit kulkevat Metalta sen omaan webhook-kohteeseen, ja sosiaalisen median kommentit ja yksityisviestit kunkin kanavan kohteeseen.

Mistä asetan tapahtumien URL-osoitteen?

Hallintapaneelissa kohdassa Profiili, sitten Kehittäjät, tai MCP-työkalulla set_partner_events_url. Allekirjoitusavain näytetään kerran, ja URL-osoitteen tallentaminen uudelleen luo uuden avaimen.

Voinko ohittaa kanavatapahtumat, jos käsittelen vain numeroita?

Kyllä. channel.*-tapahtumilla on omat nimensä ja ne sisältävät channel-objektin connection-objektin sijaan, joten vastaanotin voi ohittaa minkä tahansa tapahtuman, jonka nimi ei ala sanalla connection.

Lue lisää

Yhdistä ensimmäinen kanavasi kahdessa minuutissa.

Ei alustojen tarkastuksia odotettavana. Yhdistä WhatsApp, Instagram, TikTok tai jokin muu kanava, pyydä sitten tekoälyäsi julkaisemaan, vastaamaan tai raportoimaan ja seuraa, kun se hoitaa homman.

  • 3 päivää ilmaiseksi
  • Peruuta milloin tahansa
  • Vain viralliset API:t
  • Valvottu 24/7

Vahvistettu