Webhook לסטטוס הודעות וואטסאפ
ה-Webhook של סטטוס הודעות הוואטסאפ מאפשר לקבל לשרת שלך, בזמן אמת, כל שינוי בסטטוס של הודעות הוואטסאפ ששלחת ללקוחות: האם ההודעה נמסרה, נקראה, נכשלה או נחסמה. בשונה משאר הממשקים, כאן המערכת פונה אליך: עליך לבנות עמוד בשרת שלך, ולעדכן את כתובתו בהגדרות החשבון. ברגע שמשתנה הסטטוס של הודעה, המערכת תפנה לעמוד ותעביר את פרטי החיווי.
סקירת ה-Webhook
המערכת מאפשרת לקבל לעמוד בשרת שלך את הסטטוס של הודעות וואטסאפ ששלחת ללקוחות, בדיוק כפי שהוא מוצג בדוח ההודעות במערכת: נמסר, נקרא, נכשל או נחסם. כדי לקבל את הסטטוס עליך לבנות עמוד בשרת שלך, שאליו תפנה המערכת בכל שינוי בסטטוס של הודעה. לאחר בניית העמוד יש לעדכן את כתובתו בהגדרות החשבון במערכת. הממשק זמין לחשבון שבו פעיל שירות וואטסאפ.
חיווי נשלח על הודעות שנשלחו באחת מהדרכים הבאות:
- קמפיין וואטסאפ ששלחת מהמערכת.
- שליחה דרך ממשק ה-API לשליחת וואטסאפ.
- אוטומציה ששולחת תבנית וואטסאפ.
הגדרת העמוד שלך
- 1 בנה עמוד בשרת שלך שמקבל את הפרמטרים שהמערכת שולחת (ראו טבלת הפרמטרים למטה) ומעבד אותם.
- 2 היכנס למערכת מיקרופיי, לחץ על אייקון הפרופיל בפינת המסך, ובתפריט שנפתח בחר "הגדרות חשבון".
- 3 באזור "הגדרות טכניות" לחץ על "עדכן", הזן את כתובת העמוד בשדה "כתובת URL לקבלת חיווים להודעות וואטסאפ", ובחר את פורמט החיווי: GET (ברירת מחדל) או JSON.
- 4 שמור. מעתה, בכל שינוי בסטטוס של הודעת וואטסאפ בשליחות שהתחילו אחרי השמירה, המערכת תפנה לעמוד שהגדרת.
כתובת ציבורית: הכתובת חייבת להיות כתובת אינטרנט ציבורית שהשרתים שלנו יכולים לפנות אליה. כתובת שמפנה לרשת פנימית לא תתקבל.
מומלץ https: כתובת http רגיל בפורמט GET חייבת להשתמש בפורט ברירת המחדל (80) ולכלול נתיב לעמוד, לדוגמה
http://www.mysite.co.il/waStatus.php. כתובת עם פורט אחר (כמו :8080) או בלי נתיב לא תקבל חיווים. בכתובת https, או בפורמט JSON, אין מגבלה זו.
מתי החיווים מתחילים ומפסיקים: ההחלטה אם לשלוח חיווים מתקבלת פעם אחת, בתחילת כל שליחה (קמפיין או בקשת API). לכן חיווים נשלחים רק על שליחות שהתחילו אחרי שהגדרת את הכתובת, וקמפיין שכבר היה בשליחה בזמן השמירה לא ידווח. מחיקת הכתובת מפסיקה חיווים חדשים, אך חיווים שכבר ממתינים לשליחה, וכישלונות של קמפיין שכבר נמצא בשליחה, עשויים עוד להישלח לכתובת הקודמת במשך זמן קצר.
Content-Type: application/json. שתי השיטות מעבירות בדיוק את אותם שדות.
שיטת ה-HTTP בפורמט GET: כאשר כתובת העמוד היא https, הפנייה מתבצעת כבקשת
HEAD (הפרמטרים בכתובת ה-URL, ללא הורדת גוף התשובה). כאשר הכתובת היא http רגיל, הפנייה מתבצעת כבקשת GET. לכן ודא שהעמוד שלך קורא את הפרמטרים משורת הכתובת (למשל $_GET ב-PHP, שמאוכלס גם בבקשת HEAD), ואינו מתנה את פעולתו בכך ש-REQUEST_METHOD הוא דווקא GET.
הפרמטרים שהמערכת שולחת
| פרמטר | ערכים | תיאור |
|---|---|---|
type | מחרוזת | סוג החיווי. תמיד wastatus: חיווי על סטטוס של הודעת וואטסאפ. |
msgid | מספר | קוד המשימה (taskId) שקיבלת בתגובת בקשת השליחה, או קוד הקמפיין במערכת. יחד עם phone הוא מזהה את ההודעה. |
phone | מספר טלפון | מספר הטלפון אליו נשלחה ההודעה. מספר ישראלי בפורמט מקומי (לדוגמה 0541234567), ומספר מחו"ל בפורמט בינלאומי מלא עם קידומת המדינה (לדוגמה 447911123456). |
status | מחרוזת | הסטטוס החדש של ההודעה: delivered, read, failed או blocked. ראו את טבלת ערכי הסטטוס למטה. |
code | מספר | קוד השגיאה של וואטסאפ, בסטטוס failed או blocked (לדוגמה 131026). בסטטוסים האחרים, וגם בכישלון שאינו שגיאה של וואטסאפ (לדוגמה תקלת תקשורת): 0. |
reason | טקסט | תיאור השגיאה כפי שהתקבל מוואטסאפ, באנגלית, עד 100 תווים. כשאין שגיאה: 0. |
date | תאריך ושעה | מועד שינוי הסטטוס, לפי שעון ישראל, בפורמט YYYY-MM-DD HH:MM:SS. |
from | מספר טלפון | מספר הוואטסאפ שממנו נשלחה ההודעה, באותו פורמט כמו phone. |
pid | מספר | קוד רשימת התפוצה, כאשר ההודעה נשלחה לרשימת תפוצה (אותו קוד שנשלח בפרמטר pid בבקשת השליחה). אחרת: 0. |
ערכי הסטטוס
| ערך | בדוח ההודעות | משמעות |
|---|---|---|
delivered | נמסר | ההודעה נמסרה למכשיר הנמען. |
read | נקרא | הנמען קרא את ההודעה. נמען שביטל את אישורי הקריאה בוואטסאפ לא ידווח כ-read. |
failed | נכשל | ההודעה לא נמסרה. כולל כישלון שהתקבל כבר בזמן השליחה, גם כשהסיבה קשורה לנמען. הסיבה המדויקת בשדה code. |
blocked | נחסם | ההודעה לא נמסרה מסיבה שקשורה לנמען: המספר אינו רשום בוואטסאפ (131026), ההודעה נשלחה מחוץ לחלון 24 השעות (131047), או שוואטסאפ עצרה אותה בגלל מגבלת הודעות שיווקיות לנמען (131049). |
delivered ואחריו read. ייתכן ש-read יגיע בלי delivered לפניו. הסטטוסים failed ו-blocked הם סופיים.
דוגמת חיווי בפורמט GET
אם, לדוגמה, כתובת העמוד שהגדרת היא https://www.mysite.co.il/waStatus.php, המערכת תפנה אליו עם הפרמטרים משורשרים לכתובת. מכיוון שהכתובת היא https, הפנייה מתבצעת כבקשת HEAD:
HEAD https://www.mysite.co.il/waStatus.php?type=wastatus&msgid=348812&phone=0541234567&status=read&code=0&reason=0&date=2026-10-07+14%3A32%3A05&from=0531112233&pid=0
דוגמה לחיווי על הודעה שנחסמה כי המספר אינו רשום בוואטסאפ:
HEAD https://www.mysite.co.il/waStatus.php?type=wastatus&msgid=348812&phone=0541234568&status=blocked&code=131026&reason=Message+undeliverable&date=2026-10-07+14%3A32%3A07&from=0531112233&pid=0
אם כתובת העמוד היא http רגיל (ללא TLS), אותה פנייה מתבצעת כבקשת GET במקום HEAD, עם אותם פרמטרים בדיוק. בשני המקרים העמוד שלך קורא את הפרמטרים משורת הכתובת, מעבד אותם, ומחזיר קוד HTTP 200.
דוגמת חיווי בפורמט JSON
אם בחרת בפורמט JSON, המערכת שולחת בקשת POST לכתובת שהגדרת, עם גוף JSON המכיל את אותם שדות (כל הערכים כמחרוזת):
POST https://www.mysite.co.il/waStatus.php
Content-Type: application/json
{"type":"wastatus","msgid":"348812","phone":"0541234567","status":"delivered","code":"0","reason":"0","date":"2026-10-07 14:32:05","from":"0531112233","pid":"0"}json_decode(file_get_contents("php://input"), true), ולא דרך $_POST.
תגובת השרת שלך
העמוד שלך צריך להחזיר קוד HTTP 200 בלבד, אין צורך להחזיר תוכן בגוף התשובה.
בכתובת https או בפורמט JSON, אם העמוד מחזיר קוד אחר, או שאינו זמין, המערכת תנסה לפנות אליו שוב עד 3 פעמים נוספות, בהפרש של 5 דקות.
בכתובת http רגיל בפורמט GET, המערכת שולחת את החיווי בלי להמתין לתשובה, ולכן ניסיון חוזר מתבצע רק כאשר אין אפשרות להתחבר לשרת שלך.
מומלץ שהעמוד יענה מהר, בפחות משנייה, ויבצע עיבוד כבד ברקע: עמוד איטי או לא זמין מעכב את קבלת החיווים אצלך.
שאלות נפוצות
על אילו הודעות וואטסאפ נשלח חיווי?
על הודעות שנשלחו בקמפיין וואטסאפ מהמערכת, דרך ממשק ה-API לשליחת וואטסאפ, או מאוטומציה ששולחת תבנית. על הודעות שנשלחו מהצ'אט, ועל קודי אימות שנשלחו בממשק ה-OTP, לא נשלח חיווי.
למה לא מתקבל חיווי על שליחת ההודעה?
המערכת מדווחת רק על שינוי בסטטוס של ההודעה: נמסר, נקרא, נכשל או נחסם. הודעה שהתקבלה לשליחה ולא השתנה לה הסטטוס נשארת במצב נשלח, ולא נשלח עליה חיווי. כישלון שמתקבל כבר בזמן השליחה מדווח כ-failed.
מה ההבדל בין failed לבין blocked?
blocked (נחסם) הוא כישלון שנובע מהנמען: המספר אינו רשום בוואטסאפ, ההודעה נשלחה מחוץ לחלון 24 השעות, או שוואטסאפ עצרה את ההודעה בגלל מגבלת הודעות שיווקיות לנמען. failed (נכשל) הוא כל כישלון אחר. בשני המקרים קוד השגיאה המדויק נשלח בשדה code.
האם החיווים מגיעים לפי הסדר?
לא בהכרח. חיווי שנכשל בפנייה לעמוד שלך נשלח שוב מאוחר יותר, ולכן read יכול להגיע לפני delivered. שמרו לכל הודעה את הסטטוס הגבוה ביותר שהתקבל, לפי הסדר delivered ואחריו read. הסטטוסים failed ו-blocked הם סופיים.
מה העמוד שלי צריך להחזיר בתגובה?
די שהעמוד יחזיר קוד HTTP 200, מהר ככל האפשר. אין צורך להחזיר תוכן. בכתובת https או בפורמט JSON, אם מוחזר קוד אחר או שהעמוד אינו זמין, המערכת מנסה שוב עד 3 פעמים נוספות, בהפרש של 5 דקות. בכתובת http בפורמט GET החיווי נשלח בלי המתנה לתשובה, ולכן ניסיון חוזר מתבצע רק כשאין אפשרות להתחבר לשרת.