כישלון שליחה ב-WhatsApp הוא אחד מכמה מצבים שונים לגמרי. איך מבדילים בין שליחה שנכשלה, מסירה שנכשלה והודעה שנעצרה להערכת איכות, ומתי לקוח באמת לא זמין.
עיקרי הדברים
- ל-Cloud API יש חמישה ערכי סטטוס מתועדים להודעה יוצאת: `sent`, `delivered`, `read`, `failed` ו-`played`. מערך השגיאות מצורף רק כאשר הסטטוס הוא `failed`.
- תשובת 200 מקריאת השליחה אינה מסירה. היא אומרת שהבקשה נקלטה, ולעיתים שההודעה נעצרה בכוונה תחילה.
- מספר טלפון שנשלח בלי סימן פלוס וקידומת מדינה עלול לקבל את קידומת המדינה של מספר העסק שלכם, ואז הנמען שנוצר אינו קיים.
- היעדר webhook כלשהו הוא ממצא בפני עצמו, והוא מצביע על מסלול תקלה אחר לגמרי מזה של סטטוס `failed`.
- "הלקוח לא זמין" היא מסקנה שדורשת קוד 131026 חוזר על מספר תקין בפורמט בינלאומי, ולא ניסיון בודד.
כישלון בשליחת הודעה ב-WhatsApp Cloud API אינו עובדה אחת אלא אחד מכמה מצבים שונים, וכל אחד מהם דורש פעולה אחרת. ההודעה יכולה להיעצר לפני היציאה, לצאת ולא להימסר, או להימסר בלי שתגיע אליכם על כך התראה כלשהי. סימון הלקוח כלא זמין הוא המסקנה האחרונה בשרשרת, לא הראשונה.
חמשת המצבים של הודעה יוצאת
התיעוד של Meta מגדיר חמישה ערכים אפשריים לשדה status ב-webhook של הודעה יוצאת, ולכל אחד מהם משמעות שונה לגמרי לגבי מה שקרה בפועל. שני שדות נוספים באותו אובייקט מספקים ראיה עקיפה: errors מצורף רק כאשר הסטטוס הוא failed, ואילו pricing ו-conversation מצורפים רק בסטטוסים sent, delivered ו-read.
| הסטטוס | מה הוא מוכיח | מה הוא אינו מוכיח |
|---|---|---|
sent | ההודעה יצאה בהצלחה מהשרתים של Meta | ששום מכשיר קיבל אותה |
delivered | ההודעה הגיעה למכשיר של המשתמש | שמישהו פתח אותה |
read | ההודעה הוצגה בשיחה פתוחה על המכשיר | שהתוכן הובן או שתגיע תשובה |
failed | כשל בשליחה או במסירה. כאן, ורק כאן, קיים מערך errors | באיזו נקודה בדיוק נעצרה ההודעה, בלי לקרוא את הקוד |
played | הודעה קולית הושמעה בפעם הראשונה | דבר מחוץ להודעות מדיה קוליות |
יש כאן מלכודת אחת שמפילה כל דוח מסירה שמניח רצף קבוע: כאשר הלקוח מקבל הודעה בזמן שמסך השיחה כבר פתוח לפניו, Meta אינה שולחת webhook של delivered כלל, מפני שהמסירה משתמעת מהקריאה. שיחה שיש בה read בלי delivered אינה תקלה בקוד שלכם.
מה בעצם מוכיחה תשובת 200 מקריאת השליחה?
היא מוכיחה שהבקשה נקלטה, ולא יותר מזה. גוף התשובה המוצלחת מכיל messaging_product, מערך contacts עם השדות input ו-wa_id, ומערך messages עם מזהה ההודעה. ההשוואה בין input לבין wa_id היא הבדיקה הזולה ביותר שקיימת: input הוא המספר בדיוק כפי ששלחתם אותו, ו-wa_id הוא הזהות שאליה Meta מיפתה אותו. אם השניים אינם תואמים למה שציפיתם, מצאתם את הבעיה עוד לפני שהסתכלתם על webhook אחד. לעלויות בנייה ותפעול ראו כמה עולה צ'אטבוט.
בהודעות תבנית מופיע לעיתים שדה נוסף, message_status, וזהו המקרה היחיד שבו תשובת 200 מלווה בהודעה שכלל לא נשלחה. הערך held_for_quality_assessment מציין שההודעה נעצרה בכוונה במסגרת מנגנון ה-pacing של Meta, שנועד לאפשר זמן למשוב מוקדם של לקוחות על תבנית. למדריך מעשי ראו איך בונים בוט וואטסאפ.
למה לא הגיע שום webhook בכלל?
מפני שהיעדר webhook אינו סטטוס. זהו מסלול תקלה נפרד, ורוב הצוותים מבזבזים עליו שעות מפני שהם מחפשים שגיאה במקום שבו אין שום אירוע. שלוש סיבות מתועדות, ואחת מהן אינה קשורה אליכם כלל:
- ההודעה נעצרה במנגנון ה-pacing. לפי התיעוד, הודעות מוחזקות משוחררות ונמסרות אם המשוב המוקדם חיובי, ונזרקות אם הוא שלילי. במקרה השלילי כל הודעה מוחזקת מייצרת webhook כושל עם קוד 132015 והתבנית עוברת לסטטוס
PAUSED. אם Meta מגיעה למועד ההכרעה הפנימי שלה בלי מספיק משוב, ההודעות משוחררות אוטומטית. - ה-webhook לא נרשם לשדה הרלוונטי ברמת האפליקציה, או שהאפליקציה לא נרשמה ל-WABA. אלה שני צעדים נפרדים, וביצוע של אחד מהם בלבד מייצר בדיוק את התסמין הזה.
- נקודת הקצה שלכם החזירה שגיאה, או שאימות החתימה נכשל מפני שגוף הבקשה עבר עיבוד לפני חישוב ה-HMAC. Meta שלחה, אתם לא קיבלתם, ובלוג שלכם אין דבר.
הבדיקה שמפרידה בין השלוש פשוטה: האם מגיע היום webhook נכנס כלשהו. אם הודעות נכנסות מלקוחות מגיעות והודעות סטטוס לא, זו בעיית מנוי לשדות. אם שום דבר לא מגיע, זו נקודת הקצה.
המספר, לפני כל דבר אחר
התיעוד של Meta ממליץ במפורש לכלול גם את סימן הפלוס וגם את קידומת המדינה בשדה הנמען, ומפרט מה קורה כשלא עושים זאת: קידומת המדינה של מספר העסק שלכם מוצמדת לתחילת המספר של הנמען. בישראל זה מתגלגל באופן צפוי. מספר שנשמר במערכת כ-0526856459 ונשלח בלי פלוס מקבל 972 מלפנים והופך למספר שאיש אינו מחזיק בו. הערך שצריך לצאת הוא +972526856459, כלומר הסרת האפס המוביל והוספת קידומת המדינה.
- מספר שהודבק מגיליון וכולל רווחים, מקפים או סוגריים אינו הבעיה. התיעוד מציין שהפורמטים האלה נתמכים.
- מספר קווי, מספר וירטואלי של מרכזייה או מספר שירות שאין מאחוריו חשבון WhatsApp הם סיבה לגיטימית ל-131026, והיא לא תשתנה בניסיון נוסף.
- מספר שנקלט מטופס חופשי בלי נרמול הוא המקור הנפוץ ביותר לכשל שנראה כמו בעיית פלטפורמה.
- שמירת
wa_idשהוחזר בשליחה המוצלחת הראשונה מסלקת את כל משפחת הבעיות הזו מכל שליחה עתידית.
הסדר שבו מריצים את הבדיקות
- פתחו את שורת ההודעה במסד הנתונים שלכם וודאו שיש בה מזהה הודעה שהוחזר מ-Meta. אם אין, הכשל קרה אצלכם ומעולם לא הגיע לפלטפורמה.
- השוו את
inputשנשלח מולwa_idשהוחזר. פער כאן מסביר את כל מה שקרה אחריו. - בדקו אם הוחזר שדה
message_statusעם הערךheld_for_quality_assessment. אם כן, אין כשל, יש המתנה. - אתרו את ה-webhook האחרון עבור אותו מזהה הודעה. אם אין אף אחד, עברו לבדיקת המנוי ונקודת הקצה במקום להמשיך כאן.
- אם הסטטוס הוא
failed, קראו את מערךerrorsכולו, כוללerror_data.details, ולא רק את שדה ההודעה הכללי. - סווגו את הקוד. 131047 אומר שחלון 24 השעות נסגר ולא שהמספר שגוי. 131049 אומר שההודעה נמנעה כדי לשמור על בריאות המערכת. 131026 הוא כשל מסירה אמיתי.
- רק אם 131026 חוזר על מספר שעבר נרמול, ביותר מניסיון אחד ובהפרש זמן, סמנו את הרשומה כלא ניתנת להשגה בערוץ הזה.
הצעד השישי הוא זה שמשנה תוצאות. קודי 131047 ו-131049 מייצרים סטטוס failed בדיוק כמו כשל מסירה אמיתי, ואף אחד מהם אינו אומר דבר על המספר. פירוט מלא של הקודים והמשמעות המעשית של כל אחד נמצא במדריך קודי השגיאה של WhatsApp Cloud API, והתנהגות התור בשליחה בנפח גדול מתוארת בניהול תור הודעות WhatsApp בנפח גבוה.
מתי "לא זמין" הוא באמת לא זמין
| הראיה שבידיכם | המסקנה המותרת |
|---|---|
| 131026 בודד על מספר שלא נורמל | שום מסקנה. תקנו את הפורמט ונסו שוב |
| 131026 חוזר על מספר בפורמט בינלאומי, בשני מועדים נפרדים | הערוץ הזה אינו מגיע ללקוח |
| 131047 | הלקוח זמין לחלוטין. חלון 24 השעות נסגר ונדרשת תבנית מאושרת |
| 131049 | ההודעה נמנעה מסיבות של בריאות המערכת, לא מסיבת נמען |
סטטוס sent בלי המשך במשך ימים | המכשיר לא היה מחובר. אין כאן עדות למספר שגוי |
| אין webhook כלל | לא נמדד דבר. הבעיה בצד הקליטה שלכם |
מתוך שש הראיות בטבלה, בדיוק אחת מצדיקה סימון של הלקוח כלא ניתן להשגה. סימון מוקדם מדי גורע לקוח פעיל מכל רשימה עתידית, וזו טעות יקרה בהרבה מניסיון שליחה נוסף. אם הכשלים מתרכזים סביב תבניות ולא סביב מספרים, נקודת ההתחלה הנכונה היא מדריך אישור תבניות WhatsApp.
מקורות
שאלות נפוצות
קיבלתי סטטוס `sent` ואז שום דבר במשך יומיים. ההודעה אבדה?
לא בהכרח. `sent` מציין שההודעה יצאה מהשרתים של Meta, והמסירה ממתינה לכך שהמכשיר של הנמען יתחבר. טלפון כבוי או ללא קליטה מייצר בדיוק את התמונה הזו. זו אינה עדות למספר שגוי, והיא אינה מצדיקה שליחה חוזרת של אותו תוכן.
למה יש לי `read` בלי `delivered` באותה שיחה?
מפני שכאשר הלקוח מקבל את ההודעה ומסך השיחה כבר פתוח לפניו, Meta אינה שולחת את ה-webhook של `delivered` כלל, והמסירה משתמעת מהקריאה. דוח שמניח רצף קבוע של שלושה אירועים יסמן את השיחה הזו כחריגה, בעוד שמדובר בהתנהגות מתועדת ותקינה לחלוטין.
תשובת 200 מהשליחה מספיקה כדי לרשום "נשלח ללקוח"?
לא. היא מתעדת שהבקשה נקלטה. בהודעות תבנית היא עשויה להגיע יחד עם `message_status` בערך `held_for_quality_assessment`, כלומר ההודעה נעצרה בכוונה. הרישום העסקי צריך להיגזר מ-webhook של `delivered`, ולא מקוד התשובה של קריאת ה-API.
איך מבדילים בין תקלה אצלנו לבין תקלה בפלטפורמה?
לפי הפיזור ולפי סוג הקוד. קוד מבני כמו 131008 או 131009 מצביע על הבקשה שלכם. עלייה פתאומית ב-131026 על פני מספרים רבים בו זמנית, מיד אחרי שינוי בקוד הנרמול, מצביעה כמעט תמיד על הנרמול ולא על הלקוחות עצמם.
להמשך קריאה
שירות רלוונטי
WhatsApp Cloud API
תבניות, אינבוקס דו-כיווני ותזכורות על ה-API הרשמי של Meta.
על הכותב
יהונתן סעדיה
מפתח פרילנסר לאוטומציה, אתרים ו-MVP
אני יהונתן סעדיה, מפתח בכיר שבונה אוטומציה עסקית, אתרים מותאמים ומוצרי MVP לעסקים קטנים ובינוניים בארה"ב, אירופה וישראל. המדריכים האלה נכתבים מתוך עבודה אמיתית עם לקוחות, לא מתיאוריה.
בוא נעבוד יחדיש לך פרויקט דומה?
ספר לי מה אתה רוצה לבנות או איזה תהליך להפוך לאוטומטי. אני חוזר תוך 24 שעות עסקים עם כמה שאלות ממוקדות, ואז עוברים על זה יחד בשיחת היכרות חינמית של 30 דקות, בלי התחייבות. בסוף יש לך היקף עבודה, לוח זמנים ומחיר קבוע - או תשובה כנה שלא שווה לבנות את זה.