Cara mengetahui kapan koneksi WhatsApp atau media sosial pelanggan terputus
easyCoexistence mengirim event status yang ditandatangani ke platform Anda saat koneksi pelanggan terhubung, terputus, dihapus, atau ditangguhkan. Nomor WhatsApp mengirim connection.connected, connection.disconnected dengan alasan dari Meta, connection.removed, connection.suspended, atau connection.token_missing. Akun media sosial mengirim padanan channel.*, tanpa token_missing. Setiap event berupa POST JSON yang ditandatangani dengan X-EC-Signature dan dicoba kembali dengan jeda bertahap selama sekitar 33 jam hingga endpoint Anda merespons 2xx.
PRIMARY_INACTIVITY: alasan dari Meta ketika perangkat utama tidak aktif selama sekitar 14 hari, sehingga nomor Coexistence terputus.
COMPANION_INACTIVITY: alasan dari Meta ketika perangkat pendamping tidak aktif selama sekitar 30 hari.
Webhook yang melaporkan pemutusan koneksi. Meta selalu mengirimnya ke URL callback default aplikasi, tidak pernah ke override.
Seberapa sering event status dicoba kembali setelah jawaban di luar 2xx, dengan jeda 1 menit hingga 24 jam, selama sekitar 33 jam.
Timestamp t tertua yang boleh diterima endpoint pada event status, dengan membandingkan HMAC dalam waktu konstan.
Event status apa saja yang ada?
Ada sembilan, dalam dua keluarga yang berbagi satu endpoint dan satu signing secret. Nomor memakai connection.*, dan akun media sosial memakai channel.*, sehingga receiver yang ditulis untuk nomor dapat melewati event saluran berdasarkan namanya. Atur endpoint di dashboard pada Profile, lalu Developers, atau dengan tool MCP set_partner_events_url. Signing secret hanya ditampilkan sekali, saat URL disimpan.
Apa yang dibawa event koneksi?
ID pengiriman, berupa UUID; nama event; 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. Beberapa event menambahkan field tingkat atas: reason pada connection.disconnected dan connection.suspended, detected_by yang bernilai health_check ketika pemeriksaan berkala easyCoexistence sendiri menemukan pemutusan, bukan webhook Meta, serta connect_session_id ketika sebuah connect session menghasilkan event tersebut.
{
"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 event saluran?
Envelope yang sama, dengan objek channel sebagai pengganti connection. Isinya adalah tampilan GET /channels/{id}: id, channel untuk jaringan, external_ref, connect_session_id, name, username, external_id, status, token_ready, webhook_url, disconnected_reason, last_checked_at, dan created_at. Tidak ada token_missing untuk saluran, karena login media sosial selalu menghasilkan token milik pelanggan sendiri. Channel.connected yang berasal dari connect session juga membawa connect_session_id di tingkat 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"
}
}Apa arti alasan pemutusan?
reason pada connection.disconnected adalah kode yang diletakkan Meta di disconnection_info pada webhook account_update-nya. Meta menyertakannya untuk nomor di aplikasi WhatsApp Business maupun Cloud API. Nilainya null jika Meta tidak memberi alasan. Berikut kode-kode dalam referensi Meta:
PRIMARY_INACTIVITY: ponsel yang menjalankan aplikasi WhatsApp Business tidak aktif sekitar 14 hari, sesuai aturan 14 hari. Connect session baru menyambungkan kembali nomor tersebut.ACCOUNT_DISCONNECTED: akun diputus melalui penegakan Meta atau oleh pelanggan, yang mungkin mencabut akses atau menghapus akun.COMPANION_INACTIVITY: perangkat pendamping tidak aktif sekitar 30 hari.BUSINESS_DOWNGRADE: nomor didaftarkan dengan aplikasi WhatsApp konsumen.CHANGE_NUMBERdanUSER_RE_REGISTERED: pelanggan mengganti nomor, atau mendaftarkannya kembali di perangkat baru.
Header apa saja yang menyertai event status?
Ada lima, pada setiap percobaan: Content-Type application/json, User-Agent easyCoexistence-webhooks/1, X-EC-Event dengan nama event, X-EC-Delivery dengan id yang sama seperti di body, dan X-EC-Signature. Signature berbunyi t=<unix>,v1=<hex>, dengan v1 adalah HMAC-SHA256 dari t, titik, dan body mentah, dikunci dengan signing secret akun Anda yang diawali whsec_. Setiap percobaan ditandatangani ulang, sehingga percobaan ulang membawa t yang baru atas body 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 pengiriman yang gagal dicoba kembali?
Percobaan pertama dikirim saat event terjadi. Jawaban di luar 2xx, tidak ada jawaban dalam 10 detik, kesalahan jaringan, atau redirect dihitung sebagai kegagalan. Event kemudian dicoba lagi dengan jeda yang makin panjang, dari 1 menit hingga 24 jam, total tujuh percobaan selama sekitar 33 jam, sebelum dibuang. Pengiriman hanya dikirim ke alamat HTTPS yang mengarah ke IP publik. Event yang terjadi saat belum ada endpoint yang diatur tidak pernah diantrekan, dan menghapus endpoint menghentikan semua yang masih tertunda.
Mengapa menangani setiap id sekali dan memeriksa occurred_at?
Karena percobaan ulang mengulang pengiriman persis sama, dengan id yang sama di body dan di X-EC-Delivery. Event yang dicoba ulang juga bisa tiba setelah event yang lebih baru. Simpan id yang sudah Anda proses dan lewati pengulangan. Lalu bandingkan occurred_at dengan status terakhir yang Anda catat untuk koneksi itu, atau baca GET /connections/{id} atau GET /channels/{id} sebelum bertindak atas event yang mungkin sudah usang.
Apa yang harus dilakukan platform saat sebuah nomor terputus?
Bertindaklah sesuai alasannya. Setelah PRIMARY_INACTIVITY, minta pelanggan membuka aplikasi WhatsApp Business, lalu kirimkan connect session baru untuk nomor yang sama. Menyambungkannya kembali pada WhatsApp Business Account yang sama mempertahankan ID koneksinya, mengembalikan tujuan webhook Anda, dan mengirim connection.connected. Setelah itu Anda membaca kredensialnya lagi. connection.token_missing berarti Meta tidak menerbitkan token pada percobaan itu. Meta hanya mengirim account_update di balik pemutusan ke callback milik aplikasi, bukan ke URL Anda, sehingga event inilah cara platform Anda mengetahuinya.
Apa yang harus dilakukan platform saat akun media sosial terputus?
Pada channel.disconnected, connect session baru dengan saluran yang sama akan login kembali akun tersebut, di bawah ID channel yang sama. channel.removed berarti akses sudah hilang: token dilupakan dan tujuan webhook dihapus, jadi atur tujuan itu lagi jika pelanggan menyambung kembali. Nomor atau saluran yang ditangguhkan kembali aktif setelah disambungkan lagi, begitu langganan Anda aktif kembali.
Kesalahan umum
- Memperlakukan percobaan ulang sebagai event baru. Percobaan itu membawa id yang sama di body dan di X-EC-Delivery, jadi catat id yang sudah diproses, atau satu pemutusan bisa memberi tahu pelanggan dua kali.
- Menerapkan event sesuai urutan kedatangan. Event yang dicoba ulang bisa mendarat setelah event yang lebih baru, jadi bandingkan occurred_at, atau baca koneksinya sebelum bertindak.
- Menyimpan ulang URL event untuk memperbaiki salah ketik tanpa memperbarui backend. Menyimpan akan menerbitkan signing secret baru, dan setiap pengiriman gagal verifikasi sampai endpoint Anda memakainya.
- Mengerjakan pekerjaan sebelum menjawab. Handler yang butuh lebih dari 10 detik dihitung gagal dan event akan kembali, jadi jawab dengan 2xx dulu lalu proses setelahnya.
easyCoexistence memantau nomor WhatsApp dan akun media sosial setiap pelanggan sepanjang waktu, lalu mengirim event yang ditandatangani ke platform Anda saat satu terhubung, terputus, dihapus, atau ditangguhkan, dengan alasan dari Meta untuk nomor yang terputus. US$ 9 hingga US$ 0.75 per koneksi per bulan, turun seiring Anda menambah koneksi, dengan 3 hari pertama gratis.
Pertanyaan yang sering diajukan
Apa arti PRIMARY_INACTIVITY?
Itu alasan dari Meta untuk memutus nomor Coexistence yang aplikasi WhatsApp Business-nya tidak digunakan di perangkat utama selama sekitar 14 hari. Connect session baru untuk pelanggan itu menyambungkan kembali nomornya.
Apakah event status menyertakan pesan?
Tidak. Event tersebut hanya mencakup status koneksi. Pesan nomor berjalan dari Meta ke tujuan webhook-nya sendiri, dan komentar serta DM media sosial ke tujuan setiap saluran.
Di mana saya mengatur URL event?
Di dashboard pada Profile, lalu Developers, atau dengan tool MCP set_partner_events_url. Signing secret ditampilkan sekali, dan menyimpan URL lagi akan menerbitkan yang baru.
Bisakah saya mengabaikan event saluran jika saya hanya menangani nomor?
Bisa. Event channel.* memiliki nama sendiri dan membawa objek channel sebagai pengganti connection, sehingga receiver dapat melewati event apa pun yang namanya tidak diawali connection.
Lanjut membaca
Hubungkan saluran pertama Anda dalam dua menit.
Tanpa menunggu peninjauan platform. Hubungkan WhatsApp, Instagram, TikTok, atau saluran lainnya, lalu minta AI Anda untuk memposting, membalas, atau membuat laporan, dan lihat hasilnya langsung.
- Gratis 3 hari
- Batalkan kapan saja
- Hanya API resmi
- Dipantau 24/7
Diverifikasi pada