התחברותהתחילו תקופת ניסיון
Meta Tech Provider

סטטוסי וובהוק (Webhook) של WhatsApp: נשלחה, נמסרה, נקראה ונכשלה

סטטוסי וובהוק מדווחים מה קרה להודעה שעסק שלח דרך WhatsApp Cloud API. הם מגיעים בשדה messages, עם מערך statuses במקום מערך messages: נשלחה (sent, וי אחד), נמסרה (delivered, שני וי), נקראה (read, שני וי כחולים), הושמעה (played, להודעות קוליות) או נכשלה (failed) עם מערך errors. התאימו את statuses[].id לערך wamid שהחזירה בקשת השליחה.

easyCoexistence מחבר את מספר אפליקציית WhatsApp Business שכבר משתמשים בו ל-Cloud API של Meta דרך Coexistence.

5

ערכי הסטטוס ש-Meta שולחת: sent, delivered, read, played (ההשמעה הראשונה של הודעות קוליות) ו-failed.

3

סטטוסים נפרדים שהודעה יוצאת אחת יכולה להפיק: sent, delivered ו-read.

v24.0

החל מגרסת Graph API זו, אובייקט השיחה מושמט, למעט הודעות בחלון נקודת הכניסה החינמי.

0

אין ממשקי API לשליפת נתוני וובהוק עבר; Meta מבקשת שתשמרו את ה-payload מיד כשהוא מגיע.

messages

כותרת X-EC-Event בסטטוס שהועבר: סטטוסים נמצאים בתוך אירועי messages, תחת value.statuses.

לאן מגיעים סטטוסי WhatsApp?

לאותו שדה messages שנושא את מה שלקוחות שולחים, באותו אובייקט ובאותה מעטפת entry ו-changes. ההבדל נמצא בתוך value: להודעה נכנסת יש מערך messages, ולסטטוס יש מערך statuses. מטפל שקורא רק את value.messages מפספס כל סטטוס בלי שום שגיאה. metadata.phone_number_id מציין איזה מהמספרים שלכם שלח את ההודעה, ומגיע איתו מערך contacts עם שם הפרופיל של הלקוח, wa_id ו-BSUID, חוץ מסטטוסים שנכשלו ומסטטוס sent של הודעות קבוצה. זו הדוגמה של Meta לתבנית שיווקית שיצאה מהשרתים של Meta:

Meta's example: a marketing message with status sent
{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Pablo M."
                },
                "wa_id": "16505551234",
                "user_id": "US.13491208655302741918"
              }
            ],
            "statuses": [
              {
                "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
                "status": "sent",
                "timestamp": "1750030073",
                "recipient_id": "16505551234",
                "recipient_user_id": "US.13491208655302741918",
                "conversation": {
                  "id": "72b14d6bd5407799e66f64d1b338e567",
                  "expiration_timestamp": "1750116480",
                  "origin": {
                    "type": "marketing"
                  }
                },
                "pricing": {
                  "billable": true,
                  "pricing_model": "PMP",
                  "type": "regular",
                  "category": "marketing"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

מה כל ערך סטטוס אומר?

כל ערך תואם סימון שהלקוח היה רואה ב-WhatsApp. סטטוס נחשב כ-read רק אחרי שההודעה נמסרה. ואם לקוח מקבל הודעה כשהצ'אט כבר פתוח, Meta שולחת read בלי סטטוס delivered קודם, כאופטימיזציה פנימית. לכן מעקב צריך לקבל read גם אם delivered לא הגיע, ולדרג את הסטטוסים במקום לצפות לכולם לפי רצף קבוע.

sentLeft Meta's servers. One gray check in WhatsApp.
deliveredReached the customer's device. Two gray checks.
readDisplayed in an open chat on the device. Two blue checks.
playedFirst play of voice messages. Blue microphone.
failedCould not be sent or delivered. Red error triangle, plus an errors array.

אילו שדות יש לאובייקט סטטוס?

פחות שדות מאשר להודעה, וכמה מהם מותנים. ההפניה של Meta מפרטת מתי כל אחד מופיע:

  • id: wamid של ההודעה ששלחתם, המפתח להתאמה.
  • status ו-timestamp: הערך, וזמן Unix שבו הופעל הוובהוק, כמחרוזת.
  • recipient_id: מספר הטלפון או מזהה הקבוצה, מושמט כששלחתם ל-BSUID והמספר אינו זמין.
  • recipient_user_id: ה-BSUID של הלקוח, מושמט בסטטוס שנכשל כששלחתם למספר טלפון.
  • recipient_type ו-recipient_participant_id: רק להודעות שנשלחו לקבוצה.
  • biz_opaque_callback_data: רק אם הגדרתם אותו בבקשת השליחה.
  • pricing: רק ב-sent ובאחד מ-delivered או read. errors: רק ב-failed.

איך מתאימים סטטוס להודעה ששלחתם?

לפי wamid. בקשת השליחה מחזירה messages[0].id, וכל סטטוס של אותה הודעה נושא את אותו ערך ב-statuses[].id. שמרו אותו לצד הרשומה שלכם בזמן השליחה, ועדכנו את הרשומה כשהסטטוסים מגיעים, תוך שמירה על הסטטוס הגבוה ביותר שהגיע, כך שאישור מסירה מאוחר לא ידרוס אישור קריאה. סטטוס שלא מופיע לו wamid מוכר נשלח ממשהו אחר במספר, כמו אוטומציה, ואפשר להתעלם ממנו או לתעד אותו.

statuses.mjs: apply status webhooks to your sends (Node.js)
// statuses.mjs: apply Meta status webhooks to the messages your system sent
const RANK = { sent: 1, delivered: 2, read: 3, played: 4 };

// value: change.value of a "messages" webhook; sends: Map of wamid -> your record
export function applyStatuses(value, sends) {
  for (const s of value.statuses ?? []) {
    const rec = sends.get(s.id); // the wamid your send request returned
    if (!rec) continue; // sent by something else, such as an automation
    if (s.status === "failed") {
      rec.status = "failed";
      rec.error = s.errors?.[0]?.code; // for example 131049, 131050 or 131026
    } else if ((RANK[s.status] ?? 0) > (RANK[rec.status] ?? 0)) {
      rec.status = s.status; // read arriving before delivered is fine; never step back
    }
    rec.updatedAt = Math.max(rec.updatedAt ?? 0, Number(s.timestamp));
  }
}

מה משתנה במספר Coexistence?

סטטוסים מתארים מה נשלח דרך ה-API: תשובות מהאוטומציות שלכם, הודעות ש-AI שלכם שלח דרך שרת MCP, וכל מה שהקוד שלכם שלח. מה שהבעלים מקליד באפליקציית WhatsApp Business מגיע לתוכנה בדרך אחרת, בשם smb_message_echoes, שמתועדת על ידי ש-Meta כמראה להודעות שנשלחו מהאפליקציה. הודעות שהגיעו בייבוא ההיסטוריה החד-פעמי נושאות סטטוס משלהן בתוך הוובהוק של ההיסטוריה, עם ערכים כמו delivered, read, played, pending ו-error.

סטטוסים מגיעים לכל מקום שאליו הולך השדה messages של המספר. ביעד ישיר Meta שולחת אותם ישר לנקודת הקצה שלכם, כי messages הוא שדה ש-Meta מאפשרת לדרוס ביעד. כשהאוטומציות פעילות וכתובת Forward URL מוגדרת, הם מגיעים לשם כאירועים מסוג messages, באותו שדה.

איך ה-AI או האוטומציה יודעים אם הודעה נמסרה?

דרך היעד שלכם, לא דרך השליחה. כש-assistant קורא ל-send_template או ל-send_message, תוצאת הכלי נושאת את wamid ואומרת ש-Meta קיבלה את ההודעה. המסירה מאושרת מאוחר יותר, במכשיר הלקוח, ומדווחת כסטטוס. ל-easyCoexistence אין היסטוריית סטטוסים לשאילתה, ואף כלי MCP לא קורא סטטוסים, ולכן סוכן שצריך אישור מסירה צריך לשלוח דרך המערכת שלכם או לקרוא את הסטטוסים שמגיעים לכתובת Forward URL שלכם.

באותו אופן באוטומציות: ריצה בלשונית Runs מציגה את צעד התגובה כבוצע ברגע ש-Meta קיבלה את ההודעה, וכשל שמדווח אחר כך מופיע רק כסטטוס failed ביעד שלכם.

טעויות נפוצות

  • חיפוש שדה statuses נפרד. הסטטוסים מגיעים בתוך השדה messages, ולכן טיפול שקורא רק את value.messages מאבד אותם בלי שום שגיאה.
  • לדרוש delivered לפני read. Meta מדלגת על סטטוס delivered כשההודעה נקראת ברגע שהגיעה.
  • להתייחס לתגובת השליחה כאל מסירה. wamid משמעו ש-Meta קיבלה את הבקשה, וכשל יכול להגיע דקות אחר כך כסטטוס failed.
  • זיהוי לקוחות לפי recipient_id בלבד. השדה מושמט כששלחתם ל-BSUID והמספר אינו זמין, ו-recipient_user_id נושא את ה-BSUID.
עושים את זה עם EasyCoexistence

סטטוסים על מה שהאוטומציות, ה-AI או הקוד שלכם שולחים מגיעים לשרת שלכם: ישירות מ-Meta במצב ישיר, או מועברים לכתובת Forward URL שלכם וחתומים בכותרת X-EC-Signature כשהאוטומציות פעילות, ואינם נשמרים כברירת מחדל. מ-US$ 9 ועד US$ 0.75 למספר מחובר בחודש, יורד ככל שמוסיפים מספרים, כולל תקופת ניסיון של 3 ימים.

שאלות נפוצות

האם סטטוסים כוללים את הטקסט של ההודעה?

לא. סטטוס נושא את wamid, את הסטטוס, את הנמען, חותמות זמן ובמקום שרלוונטי תמחור ושגיאות. שמרו עותק משלכם של מה ששלחתם, לפי wamid, אם צריך להציג אותו לצד הסטטוס שלו.

אפשר לשלוף סטטוסים ישנים מ-Meta מאוחר יותר?

לא. מדריך הוובהוק של Meta קובע שאין ממשקי API לשליפת נתוני וובהוק היסטוריים, ולכן סטטוס שנקודת הקצה שלכם לא שמרה נעלם אחרי ש-Meta מפסיקה לנסות שוב, עד 7 ימים.

לשם מה משמש biz_opaque_callback_data?

זו מחרוזת שמגדירים בשליחה, כמו מספר הזמנה או פנייה משלכם. Meta מחזירה אותה ב-statuses של אותה הודעה, כך שאפשר להתאים סטטוס לרשומה שלכם בלי לחפש קודם לפי המזהה של ההודעה.

האם צריך להשיב לסטטוסים בקוד 200?

כן, כמו בכל בקשת POST של וובהוק. Meta רואה בכל תשובה אחרת שליחה שנכשלה ומנסה שוב, וזו אחת הדרכים שבהן אותו סטטוס מגיע אליכם פעמיים.

המשיכו לקרוא

למה הודעת WhatsApp נכשלה: קריאת סטטוס failed והשגיאות שלוסטטוס failed אומר ש-Meta לא הצליחה לשלוח או למסור את הודעת WhatsApp. קראו את מערך errors ואת קודי השגיאה הנפוצים, למשל 131047, ומה לעשות.אובייקט התמחור בוובהוק של WhatsApp: type, category ו-billable (2026)מה אובייקט התמחור בוובהוקים של סטטוס WhatsApp מציין מאוקטובר 2026: billable, pricing_model, type, category ו-subtype, וכיצד סופרים חיובים.ניסיונות חוזרים, כפילויות וסדר בוובהוקים (Webhook) של WhatsApp: איך לטפל בהםMeta מנסה שוב לשלוח וובהוקים של WhatsApp עד 7 ימים, לכן כפילויות הן רגילות והסדר אינו מובטח. מפתחות לסינון, מטפל בטוח ומה להחזיר.וובהוק שיחות WhatsApp: אירועי Calling API, ושיחות על מספר Coexistenceשדה calls בוובהוק מדווח על אירועי Calling API: חיבור, סיום, סטטוסי שיחה והקלטות. מטענים אמיתיים, ומה חל על מספרי Coexistence.איך הודעות WhatsApp מגיעות לשרת שלכם: ישירות או מנוהלות, ואימות החתימהישיר: Meta שולחת לשרת שלכם. מנוהל: אוטומציות עונות ועותק חתום נשלח ל-Forward URL. ה-payload, X-EC-Signature ב-Node ו-Python, וניסיונות חוזרים.שמות משתמש ב-WhatsApp ומזהי BSUID: מה משתנה בוובהוקים (Webhook) של Cloud APIאיך שמות משתמש ב-WhatsApp משנים את הוובהוקים של Cloud API: ה-BSUID בשדה user_id, מתי השדה wa_id נעלם, מענה לנמען ושינויים ב-Coexistence.

מוכנים להתחיל?

מגדירים WhatsApp Coexistence בתוך דקות, לא חודשים. האפליקציה ממשיכה לעבוד בטלפון.

התחילו תקופת ניסיון בחינם

נבדק ב-