Paano malalaman kapag nawalan ng koneksyon ang customer sa WhatsApp o social account
Nagpapadala ang easyCoexistence ng naka-sign na status event sa inyong platform kapag kumonekta, nawalan ng koneksyon, natanggal, o sinuspinde ang koneksyon ng isang customer. Ang WhatsApp na numero ay nagpapadala ng connection.connected, connection.disconnected kasama ang reason ng Meta, connection.removed, connection.suspended, o connection.token_missing. Ang social account naman ay nagpapadala ng katumbas na channel.*, maliban sa token_missing. Bawat isa ay JSON POST na naka-sign gamit ang X-EC-Signature at ni-retry nang may backoff sa loob ng mga 33 oras hanggang sumagot ng 2xx ang endpoint ninyo.
PRIMARY_INACTIVITY: reason ng Meta kapag hindi nagamit ang primary device nang humigit-kumulang 14 na araw, kaya nadidiskonekta ang isang Coexistence na numero.
COMPANION_INACTIVITY: reason ng Meta kapag hindi nagamit ang companion device nang mga 30 araw.
Ang webhook na nag-uulat ng pagkadiskonekta. Palaging ipinapadala ito ng Meta sa default callback URL ng app, hindi kailanman sa override.
Gaano kadalas sinusubukan ulit ang status event kapag may sagot na labas sa 2xx, may pagitang 1 minuto hanggang 24 na oras, sa loob ng mga 33 oras.
Pinakamatandang signed timestamp t na dapat tanggapin ng endpoint para sa status event, at ikinukumpara ang HMAC sa constant time.
Anu-ano ang mga status event?
Siyam, nasa dalawang pamilya na nagbabahagi ng iisang endpoint at iisang signing secret. Ang mga numero ay gumagamit ng connection.* at ang social account ay gumagamit ng channel.*, kaya maaaring laktawan ng receiver na isinulat para sa mga numero ang mga channel event sa pamamagitan ng pangalan. Itakda ang endpoint sa dashboard sa ilalim ng Profile, pagkatapos Developers, o gamit ang MCP tool na set_partner_events_url. Ipinapakita nang isang beses ang signing secret, kapag na-save ang URL.
Ano ang laman ng koneksyon event?
Ang id ng delivery, isang UUID; ang pangalan ng event; ang occurred_at sa ISO 8601; at isang connection object na may id, external_ref, connect_session_id, phone, name, waba_id, phone_number_id, status at token_ready. May ilang event na nagdadagdag ng top-level na field: reason sa connection.disconnected at connection.suspended, detected_by na nakatakda sa health_check kapag ang sariling periodic check ng easyCoexistence ang nakatuklas ng pagbaba at hindi ang webhook ng Meta, at connect_session_id kapag may connect session na gumawa ng event.
{
"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"
}Ano ang laman ng channel event?
Parehong envelope, pero ang channel object ang nasa halip na connection object. Ito ang GET /channels/{id} view: id, channel para sa network, external_ref, connect_session_id, name, username, external_id, status, token_ready, webhook_url, disconnected_reason, last_checked_at at created_at. Walang token_missing para sa channel, dahil ang social sign-in ay laging nagbibigay ng sariling token ng customer. Ang channel.connected na galing sa connect session ay may connect_session_id din sa top level.
{
"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"
}
}Ano ang ibig sabihin ng mga reason ng pagkadiskonekta?
Ang reason sa connection.disconnected ay ang code na inilagay ng Meta sa disconnection_info ng account_update webhook nito, na kasama para sa mga numero sa parehong WhatsApp Business app at Cloud API. Null ito kapag walang ibinigay na reason ang Meta. Ito ang mga code ayon sa reference ng Meta:
PRIMARY_INACTIVITY: hindi nagamit ang telepono na may WhatsApp Business app nang mga 14 na araw, ang 14-day rule. Muling i-connect ng bagong connect session ang numero.ACCOUNT_DISCONNECTED: na-disconnect ang account sa pamamagitan ng enforcement ng Meta o ng customer, na maaaring nag-alis ng access o nag-delete ng account.COMPANION_INACTIVITY: hindi nagamit ang isang companion device nang mga 30 araw.BUSINESS_DOWNGRADE: nakarehistro ang numero sa consumer WhatsApp app.CHANGE_NUMBERatUSER_RE_REGISTERED: pinalitan ng customer ang numero, o muling nagparehistro nito sa bagong device.
Anong mga header ang kasama sa status event?
Lima, sa bawat pagsubok: Content-Type application/json, User-Agent easyCoexistence-webhooks/1, X-EC-Event na may pangalan ng event, X-EC-Delivery na kapareho ng id sa body, at X-EC-Signature. Ganito ang itsura ng signature: t=<unix>,v1=<hex>, kung saan ang v1 ay HMAC-SHA256 ng t, isang tuldok, at ang raw body, na ginagamitan ng signing secret ng account ninyo na nagsisimula sa whsec_. Bawat pagsubok ay may bagong signature, kaya ang retry ay may bagong t sa parehong body.
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 200Paano ni-retry ang mga delivery na pumalya?
Lalabas ang unang pagsubok sa mismong sandali ng event. Ang sagot na labas sa 2xx, walang sagot sa loob ng 10 segundo, network error, o redirect ay ituturing na pagkabigo, at susubukang muli ang event na may lumalaking pagitan, mula 1 minuto hanggang 24 na oras, pitong pagsubok sa kabuuan sa loob ng mga 33 oras, bago ito burahin. Sa HTTPS na address lamang napupunta ang delivery na nareresolba sa public IP. Ang event na nangyari habang walang endpoint na nakatakda ay hindi kailanman pinipila, at ang pag-alis ng endpoint ay humihinto sa anumang nakabinbin.
Bakit dapat i-handle ang bawat id nang isang beses at tingnan ang occurred_at?
Dahil inuulit ng retry ang delivery nang eksakto, na may parehong id sa body at sa X-EC-Delivery, at dahil ang naulit na event ay maaaring dumating pagkatapos ng mas bagong event. I-store ang mga id na naproseso na ninyo at laktawan ang mga ulit. Pagkatapos, ikumpara ang occurred_at sa huling state na naitala ninyo para sa koneksyong iyon, o basahin ang GET /connections/{id} o GET /channels/{id} bago kumilos sa event na maaaring luma na.
Ano ang dapat gawin ng platform kapag bumaba ang numero?
Kumilos ayon sa reason. Pagkatapos ng PRIMARY_INACTIVITY, hilingin sa customer na buksan ang WhatsApp Business app at padalhan siya ng bagong connect session para sa parehong numero. Ang muling pag-connect nito sa parehong WhatsApp Business Account ay pinananatili ang ID ng koneksyon nito, ibinabalik ang webhook destination ninyo, at nagpapadala ng connection.connected. Pagkatapos nito, babasahin ninyo ulit ang credentials nito. Ang connection.token_missing naman ay nangangahulugang walang token na inisyu ng Meta sa run na iyon. Ang account_update na nasa likod ng pagbaba ay ipinapadala ng Meta sa callback ng app lamang, hindi sa URL ninyo, kaya ang event na ito ang paraan para malaman ito ng platform ninyo.
Ano ang dapat gawin ng platform kapag bumaba ang social account?
Sa channel.disconnected, muling pinapapasok ng bagong connect session na may parehong channel ang account sa ilalim ng parehong channel ID. Nangangahulugan ang channel.removed na wala na ang access: nakakalimutan ang token at nabubura ang anumang webhook destination, kaya itakda muli ang destination kapag nag-reconnect ang customer. Ang suspendidong numero o channel ay bumabalik sa pamamagitan ng pag-reconnect nito kapag aktibo na ulit ang subscription ninyo.
Mga karaniwang pagkakamali
- Pagtrato sa retry bilang bagong event. Ito ay may parehong id sa body at sa X-EC-Delivery, kaya itala ang mga naprosesong id, o maaaring dalawang beses ma-alert ang customer dahil sa iisang pagbaba.
- Pag-apply ng mga event ayon sa pagdating. Maaaring dumating ang naulit na event pagkatapos ng mas bago, kaya ikumpara ang occurred_at, o basahin muna ang koneksyon bago kumilos.
- Pag-save muli ng events URL para itama ang typo nang hindi ina-update ang backend. Naglalabas ang pag-save ng bagong signing secret, at lahat ng delivery ay papalya sa verification hanggang gamitin ng endpoint ninyo ito.
- Paggawa ng trabaho bago sumagot. Ang handler na lumalampas ng 10 segundo ay ituturing na pumalya at babalik ang event, kaya sumagot muna ng 2xx at iproseso pagkatapos.
Pinagmo-monitor ng easyCoexistence ang WhatsApp na numero at social account ng bawat customer nang 24 na oras kada araw. Nagpapadala ito sa inyong platform ng naka-sign na event kapag may kumonekta, nawalan ng koneksyon, natanggal, o sinuspinde, kasama ang reason ng Meta para sa numerong bumaba. Mula US$ 9 kada naka-connect na numero kada buwan, bumababa hanggang US$ 0.75 habang dumarami ang numero, at may 3 araw na free trial.
Mga madalas itanong
Ano ang ibig sabihin ng PRIMARY_INACTIVITY?
Ito ang reason ng Meta sa pagdiskonekta ng isang Coexistence na numero na hindi nagamit ang WhatsApp Business app sa primary device nito nang mga 14 na araw. Muling i-connect ng bagong connect session para sa customer na iyon ang numero.
Kasama ba sa status event ang mga mensahe?
Hindi. Sakop nila ang status ng koneksyon. Ipinapadala ng Meta ang mga mensahe ng numero sa sarili nitong webhook destination, at ang mga comment at DM sa social ay sa destination ng bawat channel.
Saan ko itatakda ang events URL?
Sa dashboard sa ilalim ng Profile, pagkatapos Developers, o gamit ang MCP tool na set_partner_events_url. Ipinapakita nang isang beses ang signing secret, at kapag inulit ang pag-save ng URL, maglalabas ito ng bagong secret.
Maaari ko bang balewalain ang channel event kung numero lang ang hawak ko?
Oo. May sarili silang pangalan, at channel object ang nasa halip na connection object. Kaya maaaring laktawan ng receiver ang alinmang event na hindi nagsisimula sa connection.
Magpatuloy sa pagbabasa
I-connect ang inyong unang channel sa loob ng dalawang minuto.
Walang review ng platform na hihintayin. I-connect ang WhatsApp, Instagram, TikTok o iba pang channel, pagkatapos ay utusan ang inyong AI na mag-post, mag-reply o gumawa ng report, at panoorin itong gumana.
- 3 araw na libre
- Mag-cancel anumang oras
- Official API lang
- Minomonitor 24/7
Na-verify noong