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.
PRIMARY_INACTIVITY: sebab Meta apabila peranti utama tidak aktif selama lebih kurang 14 hari, lalu memutuskan sambungan nombor Coexistence.
COMPANION_INACTIVITY: sebab Meta apabila peranti sahabat tidak aktif selama lebih kurang 30 hari.
Webhook yang melaporkan pemutusan sambungan. Meta sentiasa menghantarnya ke URL panggil balik lalai aplikasi, tidak pernah ke penggantian.
Kekerapan peristiwa status dicuba semula selepas sebarang respons di luar 2xx, dengan jarak 1 minit hingga 24 jam, selama kira-kira 33 jam.
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.
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.
{
"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.
{
"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_NUMBERdanUSER_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.
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 200Bagaimana 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.
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