איך לדעת מתי חיבור של לקוח ב-WhatsApp או ברשת חברתית מתנתק
easyCoexistence שולחת אירועי סטטוס חתומים לפלטפורמה שלכם כשחיבור של לקוח מתחבר, מתנתק, מוסר או מושעה. מספר WhatsApp שולח את connection.connected, connection.disconnected עם הסיבה של Meta, connection.removed, connection.suspended או connection.token_missing. חשבון ברשת חברתית שולח את האירועים המקבילים מסוג channel.*, בלי token_missing. כל אירוע הוא בקשת POST עם ה-JSON, חתום ב-X-EC-Signature, ונשלח שוב בהמתנה הולכת וגדלה במשך כ-33 שעות, עד שנקודת הקצה שלכם תאשר את הקבלה.
PRIMARY_INACTIVITY: הסיבה של Meta כשהמכשיר הראשי לא היה פעיל במשך כ-14 ימים, ומנתקת מספר Coexistence.
COMPANION_INACTIVITY: הסיבה של Meta כשמכשיר משני לא היה פעיל במשך כ-30 ימים.
וובהוק (Webhook) שמדווח על ניתוק. Meta שולחת אותו תמיד לכתובת ה-callback ברירת המחדל של האפליקציה, ולעולם לא לעקיפה.
כמה פעמים מנסים שוב לשלוח אירוע סטטוס אחרי כל תשובה שאינה 2xx, בהפרשים של דקה עד 24 שעות, במשך כ-33 שעות.
חותמת הזמן t החתומה הישנה ביותר שנקודת קצה צריכה לקבל באירוע סטטוס, תוך השוואת ה-HMAC בזמן קבוע.
אילו אירועי סטטוס קיימים?
תשעה, בשתי משפחות שחולקות נקודת קצה אחת וסוד חתימה אחד. מספרים משתמשים בשמות connection.* וחשבונות ברשתות חברתיות בשמות channel.*, כך שמקבל שנכתב למספרים יכול לדלג על אירועי channel לפי השם. מגדירים את נקודת הקצה בלוח הבקרה תחת Profile ואז Developers, או עם הכלי set_partner_events_url בשרת MCP. סוד החתימה מוצג פעם אחת, כשכתובת ה-URL נשמרת.
מה אירוע חיבור כולל?
המזהה של המשלוח, UUID; שם האירוע; occurred_at בפורמט ISO 8601; ואובייקט connection עם השדות id, external_ref, connect_session_id, phone, name, waba_id, phone_number_id, status, token_ready. חלק מהאירועים מוסיפים שדה ברמה העליונה: השדה reason מופיע באירועים connection.disconnected ו-connection.suspended; השדה detected_by מקבל את הערך health_check כשהבדיקה התקופתית של easyCoexistence מצאה את הניתוק ולא הוובהוק של Meta; והשדה connect_session_id מופיע כשסשן חיבור יצר את האירוע.
{
"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"
}מה אירוע ערוץ כולל?
אותה מעטפה עם אובייקט channel במקום connection. זו התצוגה של GET /channels/{id}: id, channel עבור הרשת, external_ref, connect_session_id, name, username, external_id, status, token_ready, webhook_url, disconnected_reason, last_checked_at ו-created_at. אין token_missing לערוצים, כי כניסה חברתית תמיד מחזירה את אסימון הגישה (Access Token) של הלקוח עצמו. ואירוע channel.connected שנוצר מסשן חיבור נושא גם הוא connect_session_id ברמה העליונה.
{
"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"
}
}מה הסיבות לניתוק?
השדה reason באירוע connection.disconnected הוא הקוד ש-Meta שמה בתוך disconnection_info של הוובהוק account_update שלה, שנשלח למספרים גם באפליקציית WhatsApp Business וגם ב-Cloud API. הערך הוא null כש-Meta לא נתנה סיבה. הקודים לפי מסמך הייחוס של Meta:
PRIMARY_INACTIVITY: הטלפון שמריץ את אפליקציית WhatsApp Business לא היה פעיל במשך כ-14 ימים, הכלל של 14 הימים. סשן חיבור חדש מחבר את המספר מחדש.ACCOUNT_DISCONNECTED: החשבון נותק דרך האכיפה של Meta או על ידי הלקוח, שאולי הסיר גישה או מחק את החשבון.COMPANION_INACTIVITY: מכשיר משני לא היה פעיל במשך כ-30 ימים.BUSINESS_DOWNGRADE: המספר היה רשום באפליקציית WhatsApp הצרכנית.CHANGE_NUMBER,USER_RE_REGISTERED: הלקוח שינה את המספר, או נרשם אליו מחדש במכשיר חדש.
אילו כותרות מגיעות עם אירוע סטטוס?
חמש, בכל ניסיון: Content-Type עם application/json, User-Agent עם easyCoexistence-webhooks/1, X-EC-Event עם שם האירוע, X-EC-Delivery עם אותו מזהה כמו בגוף, וכותרת X-EC-Signature. החתימה נראית כך: t=<unix>,v1=<hex>, כאשר v1 הוא HMAC-SHA256 של t, נקודה והגוף הגולמי. סוד החתימה של החשבון שלכם מתחיל ב-whsec_, והוא המפתח לחתימה. כל ניסיון נחתם מחדש, כך שניסיון חוזר נושא t חדש על אותו גוף.
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איך משלוחים שנכשלו נשלחים שוב?
הניסיון הראשון יוצא ברגע שהאירוע קורה. תשובה שאינה 2xx, אין תשובה תוך 10 שניות, שגיאת רשת או הפניה נחשבים ככישלון, והאירוע מנוסה שוב בהפרשים שגדלים, מדקה עד 24 שעות, שבעה ניסיונות בסך הכול במשך כ-33 שעות, לפני שהוא נמחק. משלוחים נשלחים רק לכתובת HTTPS שמתפענחת לכתובת IP ציבורית. אירוע שמתרחש כשאין נקודת קצה מוגדרת לא נשמר בתור, ומחיקת נקודת הקצה עוצרת כל מה שממתין.
מדוע לטפל בכל מזהה פעם אחת ולבדוק את occurred_at?
כי ניסיון חוזר משכפל את המשלוח בדיוק, עם אותו מזהה בגוף ובכותרת X-EC-Delivery, וכי אירוע שנוסה שוב עלול להגיע אחרי אירוע חדש יותר. שמרו את המזהים שעיבדתם ודלגו על חזרות. לאחר מכן השוו את occurred_at עם הסטטוס האחרון שרשמתם לאותו חיבור, או קראו את GET /connections/{id} או GET /channels/{id} לפני פעולה על אירוע שאולי כבר לא עדכני.
מה על פלטפורמה לעשות כשמספר מתנתק?
לפעול לפי הסיבה. אחרי PRIMARY_INACTIVITY, בקשו מהלקוח לפתוח את אפליקציית WhatsApp Business ושלחו לו סשן חיבור חדש לאותו מספר. חיבור מחדש בחשבון WhatsApp Business הזהה שומר על מזהה החיבור, מחזיר את יעד הוובהוק שלכם ושולח connection.connected, ואחר כך קראו שוב את פרטי ההתחברות שלו. connection.token_missing פירושו שלא הונפק אסימון בהרצה הזו. Meta שולחת את account_update שמאחורי הניתוק רק לכתובת ה-callback של האפליקציה, לעולם לא לכתובת שלכם, ולכן האירוע הזה הוא הדרך שבה הפלטפורמה שלכם נודעת לו.
מה על פלטפורמה לעשות כשחשבון ברשת חברתית מתנתק?
באירוע channel.disconnected, סשן חיבור חדש לאותו ערוץ מחבר את החשבון מחדש, תחת אותו מזהה ערוץ. באירוע channel.removed הגישה אבדה: האסימון נמחק ויעד הוובהוק מתנקה, ולכן הגדירו את היעד מחדש אם הלקוח מתחבר שוב. מספר או ערוץ מושעה חוזר לפעולה אחרי חיבור מחדש, לאחר שהמנוי חוזר להיות פעיל.
טעויות נפוצות
- לראות בניסיון חוזר אירוע חדש. הוא נושא את אותו מזהה בגוף ובכותרת X-EC-Delivery, לכן רשמו את המזהים שעובדו, אחרת ניתוק אחד יכול להתריע בפני לקוח פעמיים.
- לעבד אירועים לפי סדר ההגעה. ניסיון חוזר עלול להגיע אחרי אירוע חדש יותר, לכן השוו את occurred_at, או קראו את החיבור לפני פעולה.
- לשמור שוב את כתובת האירועים כדי לתקן כתובת שגויה בלי לעדכן את השרת. שמירה מנפיקה סוד חתימה חדש, וכל משלוח נכשל באימות עד שנקודת הקצה שלכם משתמשת בו.
- לבצע את העבודה לפני שמחזירים תשובה. מטפל שלוקח יותר מ-10 שניות נחשב ככישלון והאירוע חוזר, לכן החזירו 2xx קודם ועבדו אחר כך.
easyCoexistence עוקבת אחרי מספר ה-WhatsApp ואחרי החשבונות החברתיים של כל לקוח, לאורך כל שעות היממה, ושולחת לפלטפורמה שלכם אירוע חתום כשחיבור מתחבר, מתנתק, מוסר או מושעה, עם הסיבה של Meta למספר שמתנתק. US$ 9 עד US$ 0.75 לחיבור בחודש, והמחיר יורד ככל שמוסיפים חיבורים, עם תקופת ניסיון של 3 ימים.
שאלות נפוצות
מה משמעות PRIMARY_INACTIVITY?
זו הסיבה של Meta לניתוק מספר Coexistence שאפליקציית WhatsApp Business שלו לא הייתה בשימוש במכשיר הראשי במשך כ-14 ימים. סשן חיבור חדש לאותו לקוח מחבר את המספר מחדש.
האם אירועי סטטוס כוללים הודעות?
לא. הם מכסים את הסטטוס של החיבור. הודעות של מספר עוברות מ-Meta ליעד הוובהוק שלו, ותגובות והודעות פרטיות של רשתות חברתיות עוברות ליעד של כל ערוץ.
איפה מגדירים את כתובת האירועים?
בלוח הבקרה תחת Profile ואז Developers, או עם הכלי set_partner_events_url בשרת MCP. סוד החתימה מוצג פעם אחת, ושמירה חוזרת של הכתובת מנפיקה סוד חדש.
אפשר להתעלם מאירועי ערוץ אם מטפלים רק במספרים?
כן. לאירועי channel.* יש שמות משלהם והם נושאים אובייקט channel במקום connection, ולכן המקבל יכול לדלג על כל אירוע שהשם שלו לא מתחיל ב-connection, כלומר על כל אירוע שאינו אירוע חיבור.
המשיכו לקרוא
מחברים את הערוץ הראשון שלכם תוך שתי דקות.
בלי לחכות לאישורים של הפלטפורמות. מחברים את WhatsApp, Instagram, TikTok או ערוץ אחר, מבקשים מה-AI לפרסם, להשיב או להפיק דוח, ורואים אותו עובד.
- 3 ימי ניסיון חינם
- ביטול בכל עת
- רק ממשקי API רשמיים
- ניטור 24/7
נבדק ב-