התחברותהתחילו תקופת ניסיון
easyCoexistence ממשקי API רשמיים

איך לדעת מתי חיבור של לקוח ב-WhatsApp או ברשת חברתית מתנתק

easyCoexistence שולחת אירועי סטטוס חתומים לפלטפורמה שלכם כשחיבור של לקוח מתחבר, מתנתק, מוסר או מושעה. מספר WhatsApp שולח את connection.connected, connection.disconnected עם הסיבה של Meta, connection.removed, connection.suspended או connection.token_missing. חשבון ברשת חברתית שולח את האירועים המקבילים מסוג channel.*, בלי token_missing. כל אירוע הוא בקשת POST עם ה-JSON, חתום ב-X-EC-Signature, ונשלח שוב בהמתנה הולכת וגדלה במשך כ-33 שעות, עד שנקודת הקצה שלכם תאשר את הקבלה.

~14 days

PRIMARY_INACTIVITY: הסיבה של Meta כשהמכשיר הראשי לא היה פעיל במשך כ-14 ימים, ומנתקת מספר Coexistence.

~30 days

COMPANION_INACTIVITY: הסיבה של Meta כשמכשיר משני לא היה פעיל במשך כ-30 ימים.

account_update

וובהוק (Webhook) שמדווח על ניתוק. Meta שולחת אותו תמיד לכתובת ה-callback ברירת המחדל של האפליקציה, ולעולם לא לעקיפה.

7 attempts

כמה פעמים מנסים שוב לשלוח אירוע סטטוס אחרי כל תשובה שאינה 2xx, בהפרשים של דקה עד 24 שעות, במשך כ-33 שעות.

5 minutes

חותמת הזמן t החתומה הישנה ביותר שנקודת קצה צריכה לקבל באירוע סטטוס, תוך השוואת ה-HMAC בזמן קבוע.

אילו אירועי סטטוס קיימים?

תשעה, בשתי משפחות שחולקות נקודת קצה אחת וסוד חתימה אחד. מספרים משתמשים בשמות connection.* וחשבונות ברשתות חברתיות בשמות channel.*, כך שמקבל שנכתב למספרים יכול לדלג על אירועי channel לפי השם. מגדירים את נקודת הקצה בלוח הבקרה תחת Profile ואז Developers, או עם הכלי set_partner_events_url בשרת MCP. סוד החתימה מוצג פעם אחת, כשכתובת ה-URL נשמרת.

connection.connectedA number connected, came back after a drop, or got its customer token on a second run.
connection.disconnectedMeta dropped the link; reason carries Meta's code when known.
connection.removedRemoved with DELETE /connections/{id} or from the dashboard.
connection.suspendedYour subscription lapsed; reason names its state.
connection.token_missingConnected without a customer token: it receives, but cannot send yet.
channel.connectedA social account connected, one event per Page when a sign-in brings several.
channel.disconnectedThe network refused the token, or the owner withdrew access.
channel.removedRemoved with DELETE /channels/{id} or from the dashboard, or the owner removed the app on Meta.
channel.suspendedYour subscription lapsed.

מה אירוע חיבור כולל?

המזהה של המשלוח, 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 מופיע כשסשן חיבור יצר את האירוע.

connection.disconnected
{
  "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 ברמה העליונה.

channel.disconnected
{
  "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 חדש על אותו גוף.

Python: verify, then handle each id once
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

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, כלומר על כל אירוע שאינו אירוע חיבור.

המשיכו לקרוא

איך מקבלים בוובהוק (Webhook) את הודעות WhatsApp ואת התגובות ברשתות החברתיות של הלקוחות שלכםוובהוק לכל חיבור: הודעות WhatsApp ישירות מ-Meta, מאומתות בסוד בכתובת, ותגובות ו-DM מהרשתות החברתיות חתומות בכותרת X-EC-Signature.איך מקבלים את אסימוני ה-API של לקוחותיכם ב-WhatsApp, Instagram ו-TikTokמה קריאת פרטי הגישה מחזירה עבור מספר WhatsApp של לקוח ועבור כל חשבון רשת, שדה אחר שדה, וכיצד פועלים סיבוב האסימונים והשדה token_ready.איך מייבאים את היסטוריית הצ'אטים ואנשי הקשר של אפליקציית WhatsApp Business דרך ה-APIייבוא אנשי קשר ועד 180 ימים של צ'אטים ממספר ב-WhatsApp Business דרך Coexistence, כולל וובהוק (Webhook) להיסטוריה ושדה chunk_order.איך לבנות מוצר סוכן AI בערוצי ה-WhatsApp, Instagram ו-TikTok של הלקוחותבנו מוצר סוכן AI בערוצי ה-WhatsApp, Instagram, Facebook ו-TikTok של הלקוחות, עם ה-Partner API, המודל שלכם וכללי כל רשת.וובהוק (Webhook) של account_update וכל סיבות הניתוקaccount_update מדווח על שינויי מצב בחיבור. כאן תמצאו את סיבות הניתוק ש-Meta שולחת, משמעותן ומהן ניתנות לשחזור.מספר הפסיק לעבוד: איך מגלים למהרשימת בדיקה לפי סדר הכשלים בפועל: אסימון, עקיפת וובהוק, ניתוק בגלל חוסר פעילות, איכות והגבלת חשבון.

מחברים את הערוץ הראשון שלכם תוך שתי דקות.

בלי לחכות לאישורים של הפלטפורמות. מחברים את WhatsApp, Instagram, TikTok או ערוץ אחר, מבקשים מה-AI לפרסם, להשיב או להפיק דוח, ורואים אותו עובד.

  • 3 ימי ניסיון חינם
  • ביטול בכל עת
  • רק ממשקי API רשמיים
  • ניטור 24/7

נבדק ב-