Jinsi ya kujua muunganisho wa mteja wa WhatsApp au mitandao ya kijamii unapokatika
easyCoexistence hutuma kwa jukwaa lako matukio ya hali yaliyotiwa sahihi wakati muunganisho wa mteja unapounganishwa, kukatika, kuondolewa au kusimamishwa. Nambari ya WhatsApp hutuma connection.connected, connection.disconnected yenye sababu ya Meta, connection.removed, connection.suspended au connection.token_missing; akaunti ya mtandao wa kijamii hutuma matukio sawa ya channel.*, bila token_missing. Kila tukio ni ombi la POST la JSON lililotiwa sahihi kwa X-EC-Signature, na hujaribiwa upya kwa vipindi vinavyoongezeka kwa takriban saa 33 hadi endpoint yako ijibu 2xx.
PRIMARY_INACTIVITY: sababu ya Meta pale simu kuu ilipokuwa haitumiki kwa takriban siku 14, hali inayokata nambari ya Coexistence.
COMPANION_INACTIVITY: sababu ya Meta pale kifaa kisaidizi kilipokuwa hakitumiki kwa takriban siku 30.
Webhook inayoripoti kukatika kwa muunganisho. Meta huituma kila mara kwenye callback URL chaguo-msingi ya programu, kamwe si kwenye URL mbadala.
Jinsi tukio la hali linavyojaribiwa tena baada ya jibu lolote nje ya 2xx, kwa mapengo ya dakika 1 hadi saa 24, kwa takriban saa 33.
Muda wa zamani zaidi wa sahihi t ambao endpoint inapaswa kukubali kwa tukio la hali, ikilinganisha HMAC kwa njia ya muda usiobadilika.
Ni matukio gani ya hali yapo?
Tisa, katika familia mbili zinazoshiriki endpoint moja na siri moja ya kutia sahihi. Nambari hutumia connection.* na akaunti za mitandao ya kijamii hutumia channel.*, hivyo kipokezi kilichoandikwa kwa nambari kinaweza kuruka matukio ya channel kwa jina. Weka endpoint kwenye dashboard chini ya Profile, kisha Developers, au kwa zana ya MCP set_partner_events_url; siri ya kutia sahihi huonyeshwa mara moja tu, URL inapohifadhiwa.
Tukio la muunganisho lina nini?
Kitambulisho cha uwasilishaji, UUID; jina la tukio; occurred_at katika ISO 8601; na kitu cha connection chenye id, external_ref, connect_session_id, phone, name, waba_id, phone_number_id, status na token_ready. Baadhi ya matukio huongeza sehemu ya juu: reason kwenye connection.disconnected na connection.suspended; detected_by yenye thamani health_check pale ukaguzi wa mara kwa mara wa easyCoexistence ulipogundua kukatika badala ya webhook ya Meta; na connect_session_id pale kikao cha muunganisho kilipozalisha tukio.
{
"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"
}Tukio la channel lina nini?
Bahasha ile ile yenye kitu cha channel badala ya connection. Ni mwonekano wa GET /channels/{id}: id, channel kwa mtandao husika, external_ref, connect_session_id, name, username, external_id, status, token_ready, webhook_url, disconnected_reason, last_checked_at na created_at. Hakuna token_missing kwa channel, kwa kuwa kuingia kwa mtandao wa kijamii daima hutoa token ya mteja mwenyewe; na channel.connected inayotokana na kikao cha muunganisho hubeba connect_session_id pia katika sehemu ya juu.
{
"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"
}
}Sababu za kukatika zina maana gani?
reason kwenye connection.disconnected ni msimbo ambao Meta uliweka kwenye disconnection_info ya webhook yake ya account_update, ambayo Meta huijumuisha kwa nambari zote za programu ya WhatsApp Business na Cloud API. Ni null pale Meta isipotoa sababu yoyote. Misimbo katika marejeleo ya Meta:
PRIMARY_INACTIVITY: simu inayoendesha programu ya WhatsApp Business haikutumika kwa takriban siku 14, kanuni ya siku 14. Kikao kipya cha muunganisho huunganisha nambari tena.ACCOUNT_DISCONNECTED: akaunti ilikatwa kupitia hatua za Meta au na mteja, ambaye huenda aliondoa ruhusa au kufuta akaunti.COMPANION_INACTIVITY: kifaa kisaidizi hakikutumika kwa takriban siku 30.BUSINESS_DOWNGRADE: nambari ilisajiliwa kwenye programu ya WhatsApp ya watumiaji wa kawaida.CHANGE_NUMBERnaUSER_RE_REGISTERED: mteja alibadilisha nambari, au aliisajili upya kwenye kifaa kipya.
Vichwa gani huja na tukio la hali?
Vitano, kwenye kila jaribio: Content-Type application/json, User-Agent easyCoexistence-webhooks/1, X-EC-Event yenye jina la tukio, X-EC-Delivery yenye id sawa na ile ya mwili wa ombi, na X-EC-Signature. Sahihi inasomeka t=<unix>,v1=<hex>, ambapo v1 ni HMAC-SHA256 ya t, nukta, na mwili ghafi, ikitumia ufunguo wa siri ya akaunti yako ambayo huanza na whsec_. Kila jaribio hutiwa sahihi upya, hivyo jaribio upya hubeba t mpya juu ya mwili uleule.
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 200Uwasilishaji ulioshindwa unajaribiwa upya vipi?
Jaribio la kwanza hutumwa tukio linapotokea. Jibu nje ya 2xx, kutojibu ndani ya sekunde 10, hitilafu ya mtandao au uelekezaji upya (redirect) huhesabiwa kama kushindwa, na tukio hujaribiwa tena kwa mapengo yanayoongezeka, kutoka dakika 1 hadi saa 24, majaribio saba kwa jumla kwa takriban saa 33, kabla halijaachwa. Uwasilishaji hutumwa tu kwa anwani ya HTTPS inayoelekeza kwenye IP ya umma. Tukio linalotokea wakati hakuna endpoint imewekwa halihifadhiwi kwenye foleni, na kuondoa endpoint kunasimamisha chochote kilichokuwa kinasubiri.
Kwa nini kila id ishughulikiwe mara moja na occurred_at ikaguliwe?
Kwa sababu jaribio upya hurudia uwasilishaji kikamilifu, ikiwa na id ileile kwenye mwili na kwenye X-EC-Delivery, na kwa sababu tukio lililojaribiwa upya linaweza kufika baada ya lile jipya zaidi. Hifadhi ids ulizoshughulikia na uruke marudio. Kisha linganisha occurred_at na hali ya mwisho uliyorekodi kwa muunganisho huo, au soma GET /connections/{id} au GET /channels/{id} kabla ya kuchukua hatua kwenye tukio ambalo huenda limepitwa na wakati.
Jukwaa lifanye nini nambari inapokatika?
Chukua hatua kulingana na sababu. Baada ya PRIMARY_INACTIVITY, mwombe mteja afungue programu ya WhatsApp Business na umtumie kikao kipya cha muunganisho kwa nambari ile ile. Kuiunganisha tena kwenye WhatsApp Business Account ile ile huhifadhi kitambulisho chake cha muunganisho, hurudisha anwani ya webhook yako na hutuma connection.connected, baada ya hapo soma vitambulisho vyake tena; connection.token_missing badala yake humaanisha kwamba Meta haikutoa token katika jaribio hilo. Meta hutuma account_update inayosababisha kukatika kwa callback ya programu yenyewe pekee, kamwe si kwenye URL yako, kwa hivyo tukio hili ndilo linaloifahamisha jukwaa lako.
Jukwaa lifanye nini akaunti ya mtandao wa kijamii inapokatika?
Kwenye channel.disconnected, kikao kipya cha muunganisho chenye channel ile ile humwingiza mteja tena, chini ya kitambulisho kile kile cha channel. channel.removed humaanisha ruhusa imepotea: token inasahauliwa na anwani yoyote ya webhook inafutwa, kwa hiyo weka anwani tena mteja akiunganisha upya. Nambari au channel iliyosimamishwa hurudi kwa kuiunganisha upya mara usajili wako utakapokuwa hai tena.
Makosa ya kawaida
- Kuchukulia jaribio upya kama tukio jipya. Lina id ileile kwenye mwili na kwenye X-EC-Delivery, kwa hivyo rekodi ids zilizoshughulikiwa, au kukatika kwa mara moja kunaweza kumtahadharisha mteja mara mbili.
- Kutumia matukio kwa mpangilio wa kuwasili. Tukio lililojaribiwa upya linaweza kutua baada ya jipya zaidi, kwa hiyo linganisha occurred_at, au soma muunganisho kabla ya kuchukua hatua.
- Kuhifadhi URL ya matukio tena ili kurekebisha kosa dogo la kuandika bila kusasisha backend. Kuhifadhi hutoa siri mpya ya kutia sahihi, na kila uwasilishaji unashindwa uthibitishaji hadi endpoint yako itumie siri hiyo.
- Kufanya kazi kabla ya kujibu. Kishughulikiaji kinachochukua zaidi ya sekunde 10 huhesabiwa kama kushindwa na tukio linarudi, kwa hiyo jibu 2xx kwanza, kisha shughulikia baadaye.
easyCoexistence inaangalia nambari ya WhatsApp ya kila mteja na akaunti zake za mitandao ya kijamii saa 24 kwa siku, na hutuma jukwaa lako tukio lililotiwa sahihi muunganisho unapounganishwa, kukatika, kuondolewa au kusimamishwa, pamoja na sababu ya Meta kwa nambari inayokatika. Kuanzia US$ 9 hadi US$ 0.75 kwa kila muunganisho kwa mwezi, inashuka unavyoongeza miunganisho, na siku 3 za kwanza bila malipo.
Maswali yanayoulizwa mara kwa mara
Je, PRIMARY_INACTIVITY inamaanisha nini?
Ni sababu ya Meta ya kukata nambari ya Coexistence ambayo programu yake ya WhatsApp Business haikutumika kwenye simu kuu kwa takriban siku 14. Kikao kipya cha muunganisho kwa mteja huyo huunganisha nambari tena.
Je, matukio ya hali yanajumuisha ujumbe?
Hapana. Yanahusu hali ya muunganisho. Ujumbe wa nambari hutoka Meta kwenda kwenye anwani yake ya webhook, na maoni na DM za mitandao ya kijamii kwenda kwenye anwani ya kila channel.
Ninaweka wapi URL ya matukio?
Kwenye dashboard chini ya Profile, kisha Developers, au kwa zana ya MCP set_partner_events_url. Siri ya kutia sahihi huonyeshwa mara moja tu, na kuhifadhi URL tena hutoa mpya.
Je, ninaweza kupuuza matukio ya channel nikishughulikia nambari pekee?
Ndiyo. Matukio ya channel.* yana majina yao na hubeba kitu cha channel badala ya connection, kwa hiyo kipokezi kinaweza kuruka tukio lolote ambalo jina lake halianzi na connection.
Endelea kusoma
Unganisha chaneli yako ya kwanza ndani ya dakika mbili.
Hakuna ukaguzi wa majukwaa wa kusubiri. Unganisha WhatsApp, Instagram, TikTok au chaneli nyingine, kisha mwombe AI wako achapishe, ajibu au atoe ripoti, na uone akifanya kazi.
- Siku 3 bila malipo
- Ghairi wakati wowote
- API rasmi pekee
- Hufuatiliwa saa 24/7
Imethibitishwa kwenye