Log masukMulakan percubaan percuma
easyCoexistence API rasmi

Cara tahu bila sambungan WhatsApp atau media sosial pelanggan terputus

easyCoexistence menghantar peristiwa status yang ditandatangani kepada platform anda apabila sambungan pelanggan tersambung, terputus, dibuang atau digantung. Nombor WhatsApp menghantar connection.connected, connection.disconnected dengan sebab daripada Meta, connection.removed, connection.suspended atau connection.token_missing; akaun media sosial menghantar setara channel.*, tanpa token_missing. Setiap satu ialah POST JSON yang ditandatangani dengan X-EC-Signature dan dicuba semula secara berperingkat selama kira-kira 33 jam sehingga endpoint anda membalas 2xx.

~14 days

PRIMARY_INACTIVITY: sebab Meta apabila peranti utama tidak aktif selama lebih kurang 14 hari, lalu memutuskan sambungan nombor Coexistence.

~30 days

COMPANION_INACTIVITY: sebab Meta apabila peranti sahabat tidak aktif selama lebih kurang 30 hari.

account_update

Webhook yang melaporkan pemutusan sambungan. Meta sentiasa menghantarnya ke URL panggil balik lalai aplikasi, tidak pernah ke penggantian.

7 attempts

Kekerapan peristiwa status dicuba semula selepas sebarang respons di luar 2xx, dengan jarak 1 minit hingga 24 jam, selama kira-kira 33 jam.

5 minutes

Cap masa bertanda tangan terlama t yang sepatutnya diterima endpoint bagi peristiwa status, dengan membandingkan HMAC secara constant time.

Apakah peristiwa status yang ada?

Sembilan, dalam dua keluarga yang berkongsi satu endpoint dan satu rahsia tandatangan. Nombor menggunakan connection.* dan akaun media sosial menggunakan channel.*, jadi penerima yang ditulis untuk nombor boleh mengabaikan peristiwa channel mengikut nama. Tetapkan endpoint dalam dashboard di bawah Profil, kemudian Developers, atau dengan alat MCP set_partner_events_url; rahsia tandatangan dipaparkan sekali sahaja, apabila URL disimpan.

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.

Apa yang dibawa oleh peristiwa sambungan?

id penghantaran, iaitu UUID; nama peristiwa; occurred_at dalam ISO 8601; dan objek connection dengan id, external_ref, connect_session_id, phone, name, waba_id, phone_number_id, status dan token_ready. Sesetengah peristiwa menambah medan peringkat atas: reason pada connection.disconnected dan connection.suspended, detected_by yang ditetapkan kepada health_check apabila semakan berkala easyCoexistence sendiri mengesan pemutusan dan bukan webhook Meta, dan connect_session_id apabila sesi sambungan menghasilkan peristiwa itu.

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

Apa yang dibawa oleh peristiwa saluran?

Sampul yang sama dengan objek channel menggantikan connection. Ia ialah paparan GET /channels/{id}: id, channel bagi rangkaian, external_ref, connect_session_id, name, username, external_id, status, token_ready, webhook_url, disconnected_reason, last_checked_at dan created_at. Tiada token_missing untuk saluran, kerana log masuk media sosial sentiasa menghasilkan token milik pelanggan sendiri, dan channel.connected yang datang daripada sesi sambungan turut membawa connect_session_id pada peringkat atas.

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

Apakah maksud sebab pemutusan?

reason pada connection.disconnected ialah kod yang Meta letakkan dalam disconnection_info bagi webhook account_update, yang Meta sertakan untuk nombor pada aplikasi WhatsApp Business dan Cloud API. Ia null apabila Meta tidak memberikan sebab. Kod dalam rujukan Meta:

  • PRIMARY_INACTIVITY: telefon yang menjalankan aplikasi WhatsApp Business tidak aktif selama kira-kira 14 hari, iaitu peraturan 14 hari. Sesi sambungan baharu menyambungkan semula nombor itu.
  • ACCOUNT_DISCONNECTED: akaun diputuskan melalui penguatkuasaan Meta atau oleh pelanggan, yang mungkin telah membuang akses atau memadam akaun.
  • COMPANION_INACTIVITY: peranti sahabat tidak aktif selama kira-kira 30 hari.
  • BUSINESS_DOWNGRADE: nombor itu didaftarkan dengan aplikasi WhatsApp pengguna biasa.
  • CHANGE_NUMBER dan USER_RE_REGISTERED: pelanggan menukar nombor, atau mendaftarkannya semula pada peranti baharu.

Header apa yang disertakan dengan peristiwa status?

Lima, pada setiap cubaan: Content-Type application/json, User-Agent easyCoexistence-webhooks/1, X-EC-Event dengan nama peristiwa, X-EC-Delivery dengan id yang sama seperti badan, dan X-EC-Signature. Tandatangan berbunyi t=<unix>,v1=<hex>, dengan v1 ialah HMAC-SHA256 bagi t, titik dan badan mentah, dikunci dengan rahsia tandatangan akaun anda yang bermula dengan whsec_. Setiap cubaan ditandatangani semula, jadi cubaan semula membawa t baharu pada badan yang sama.

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

Bagaimana penghantaran yang gagal dicuba semula?

Cubaan pertama dihantar sebaik peristiwa berlaku. Respons di luar 2xx, tiada respons dalam masa 10 saat, ralat rangkaian atau ubah hala dikira sebagai kegagalan, dan peristiwa dicuba semula dengan jarak yang kian panjang, dari 1 minit hingga 24 jam, tujuh cubaan semuanya selama kira-kira 33 jam, sebelum digugurkan. Penghantaran hanya dibuat ke alamat HTTPS yang diselesaikan kepada IP awam. Peristiwa yang berlaku semasa tiada endpoint ditetapkan tidak pernah disimpan untuk dihantar kemudian, dan membuang endpoint menghentikan apa-apa yang masih tertunggu.

Mengapa setiap id dikendalikan sekali dan occurred_at diperiksa?

Kerana cubaan semula mengulang penghantaran itu sepenuhnya, dengan id yang sama dalam badan dan dalam X-EC-Delivery, dan kerana peristiwa yang dicuba semula boleh tiba selepas peristiwa yang lebih baharu. Simpan id yang telah anda proses dan langkau pengulangan. Kemudian bandingkan occurred_at dengan keadaan terakhir yang anda rekodkan bagi sambungan itu, atau baca GET /connections/{id} atau GET /channels/{id} sebelum bertindak atas peristiwa yang mungkin sudah lapuk.

Apa yang perlu dilakukan platform apabila nombor terputus?

Bertindak mengikut sebab. Selepas PRIMARY_INACTIVITY, minta pelanggan membuka aplikasi WhatsApp Business dan hantarkan sesi sambungan baharu untuk nombor yang sama. Menyambungkan semula pada WhatsApp Business Account yang sama mengekalkan ID sambungannya, meletakkan semula destinasi webhook anda dan menghantar connection.connected, selepas itu baca kredensialnya semula; connection.token_missing pula bermaksud Meta tidak mengeluarkan token pada larian itu. Meta menghantar account_update di sebalik pemutusan hanya kepada panggil balik aplikasi sendiri, tidak pernah ke URL anda, jadi peristiwa inilah cara platform anda mengetahuinya.

Apa yang perlu dilakukan platform apabila akaun media sosial terputus?

Pada channel.disconnected, sesi sambungan baharu dengan saluran yang sama akan log masuk semula akaun itu, di bawah ID saluran yang sama. channel.removed bermaksud akses telah hilang: token dilupakan dan sebarang destinasi webhook dikosongkan, jadi tetapkan semula destinasi jika pelanggan menyambung semula. Nombor atau saluran yang digantung akan pulih apabila disambungkan semula sebaik langganan anda aktif semula.

Kesilapan biasa

  • Menganggap cubaan semula sebagai peristiwa baharu. Ia membawa id yang sama dalam badan dan dalam X-EC-Delivery, jadi rekodkan id yang telah diproses, atau satu pemutusan boleh memberi amaran kepada pelanggan dua kali.
  • Menggunakan peristiwa mengikut susunan tiba. Peristiwa yang dicuba semula boleh sampai selepas yang lebih baharu, jadi bandingkan occurred_at, atau baca sambungan sebelum bertindak.
  • Menyimpan semula URL peristiwa untuk membetulkan kesilapan ejaan tanpa mengemas kini backend. Penyimpanan mengeluarkan rahsia tandatangan baharu, dan setiap penghantaran gagal pengesahan sehingga endpoint anda menggunakannya.
  • Melakukan kerja sebelum membalas. Pengendali yang mengambil masa lebih 10 saat dikira gagal dan peristiwa itu dihantar semula, jadi balas 2xx dahulu dan proses kemudian.
Menggunakan EasyCoexistence untuk ini

easyCoexistence memantau nombor WhatsApp dan akaun media sosial setiap pelanggan sepanjang masa dan menghantar platform anda peristiwa yang ditandatangani apabila satu tersambung, terputus, dibuang atau digantung, dengan sebab Meta bagi nombor yang terputus. Daripada US$ 9 hingga US$ 0.75 setiap sambungan sebulan, menurun apabila anda menambah sambungan, dengan percubaan percuma 3 hari.

Soalan lazim

Apakah maksud PRIMARY_INACTIVITY?

Ia ialah sebab Meta untuk memutuskan sambungan nombor Coexistence yang aplikasi WhatsApp Business-nya tidak digunakan pada peranti utama selama kira-kira 14 hari. Sesi sambungan baharu untuk pelanggan itu menyambungkan semula nombor tersebut.

Adakah peristiwa status termasuk mesej?

Tidak. Ia meliputi status sambungan. Mesej nombor dihantar dari Meta ke destinasi webhook-nya sendiri, dan komen serta DM media sosial ke destinasi setiap saluran.

Di mana saya menetapkan URL peristiwa?

Dalam dashboard di bawah Profil, kemudian Developers, atau dengan alat MCP set_partner_events_url. Rahsia tandatangan dipaparkan sekali sahaja, dan menyimpan URL semula akan mengeluarkan yang baharu.

Bolehkah saya mengabaikan peristiwa saluran jika saya hanya mengendalikan nombor?

Boleh. Peristiwa channel.* mempunyai nama sendiri dan membawa objek channel dan bukan connection, jadi penerima boleh mengabaikan mana-mana peristiwa yang namanya tidak bermula dengan connection.

Teruskan membaca

Sambungkan saluran pertama anda dalam masa dua minit.

Tidak perlu menunggu semakan platform. Sambungkan WhatsApp, Instagram, TikTok atau saluran lain, kemudian minta AI anda menyiarkan, membalas atau melaporkan, dan lihat ia bekerja.

  • 3 hari percuma
  • Batal bila-bila masa
  • API rasmi sahaja
  • Dipantau 24/7

Disahkan pada