דלגו לתוכן
Wbiztool

API להודעות

ממשק API לסטטוס הודעה

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

POSThttps://wbiztool.com/api/v1/message/status/{msg_id}/

גוף הבקשה: JSON או שדות טופס

כתבו את מזהה ההודעה בכתובת ה-URL, והחליפו את {msg_id} ב-msg_id שהוחזר מ-שליחת הודעה, מ-שליחה לקבוצה, מ-שליחה למספרים מרובים או מ-תזמון הודעה. לדוגמה: https://wbiztool.com/api/v1/message/status/9817263/.

דוגמה מהירה#

curl -X POST https://wbiztool.com/api/v1/message/status/9817263/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY"
  }'

החליפו את 12345 ו-YOUR_API_KEY בערכים שלכם. בסעיף אימות מוסבר איפה למצוא אותם.

פרמטרי הבקשה#

כתובת URL

msg_idintegerחובה

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

גוף הבקשה

client_idintegerחובה

מזהה הלקוח שלכם ל-API (API Client ID) מהדף Settings → API keys.

api_keystringחובה

מפתח ה-API שלכם מאותו דף.

שימוש בלקוח הרשמי#

לקוח ה-Python קורא ל-endpoint הזה בשבילכם.

Python
from wbiztool_client import WbizToolClient

client = WbizToolClient(api_key="YOUR_API_KEY", client_id=12345)

result = client.get_message_status(msg_id=9817263)
print(result.get("status_text"), result.get("error"))

הלקוח מחזיר את אותם שדות כמו ה-API, כך ש-result["status"] הוא מצב ההודעה, ולא סימן להצלחה. שגיאות אימות זורקות requests.HTTPError; קראו את הסיבה עם e.response.json()["message"].

תגובה#

ה-endpoint מחזיר HTTP 200 עם המצב הנוכחי של ההודעה:

{
  "message": "Sent",
  "status": 1,
  "status_text": "Sent",
  "error": ""
}

הודעה שנכשלה:

{
  "message": "Failed",
  "status": 2,
  "status_text": "Failed",
  "error": "Phone number invalid"
}
שדהסוגתיאור
statusintegerקוד הסטטוס של ההודעה. ראו את הטבלה שלמטה.
status_textstringשם הסטטוס: Created, Sent, Failed, Cancelled או Expired.
messagestringאותו ערך כמו status_text.
errorstring or nullהסיבה שההודעה נכשלה. השדה תמיד קיים; הוא ריק ("" או null) כשאין שגיאה.

ערכי סטטוס#

statusstatus_textמשמעות
0Createdבתור או מתוזמנת, ממתינה לשליחה.
1Sentנשלחה ממספר ה-WhatsApp שלכם.
2Failedלא ניתן היה לשלוח אותה, או שהשליחה נקטעה. השדה error מסביר למה. אם error הוא Sending was interrupted and may have been delivered. Check WhatsApp before resending., ייתכן שההודעה כבר אצל הנמען, לכן אל תשלחו אותה שוב באופן אוטומטי.
3Cancelledבוטלה לפני שנשלחה, למשל באמצעות ביטול הודעה.
4Expiredלא נשלחה לפני המועד האחרון שנקבע ב-expire_after_seconds.

הסטטוס Sent הוא מצב ההצלחה הסופי. ה-endpoint הזה לא מדווח אם ההודעה נמסרה לטלפון או נקראה.

דוגמאות לערכי error בהודעות שנכשלו: Phone number invalid, Group not found, Image Url Error, File Url Error, Blocked Contact, File exceeds WhatsApp size limit (…), File type not supported, Sending was interrupted and may have been delivered. Check WhatsApp before resending.

שגיאות#

{
  "message": "Unknown message id",
  "status": 0,
  "status_text": "pending",
  "error": "Invalid message id"
}
הודעהאיך לתקן
Unknown message idאין הודעה עם המזהה הזה בסביבת העבודה של מפתח ה-API שלכם. בדקו את המזהה, וודאו שאתם משתמשים במפתח מאותה סביבת עבודה.
Auth Errorשלחו גם client_id וגם api_key. גוף JSON לא תקין (למשל עם פסיק מיותר בסוף) גם מחזיר Auth Error.
Invalid Client Idשלחו את client_id כמספר. מוחזר עם HTTP 403.
Auth Error: invalid api keyודאו שהמפתח קיים, לא נמחק ושייך ל-client_id הזה. מוחזר עם HTTP 400.

טיפים#

  • העדיפו webhooks לעדכונים בזמן אמת: העבירו webhook כששולחים את ההודעה, ו-Wbiztool תודיע לכם כשהיא נשלחת או נכשלת, כך שלא תצטרכו לבצע polling. הודעות שבוטלו או פגו לא מפעילות webhook, לכן בדקו אותן כאן.
  • Polling: אם אתם בכל זאת בודקים שוב ושוב, הפסיקו ברגע ש-status כבר אינו 0. השאירו כמה שניות בין בדיקה לבדיקה.
  • הודעות רבות בבת אחת: כדי לבדוק את ההודעות של יום שלם, השתמשו ב-היסטוריית הודעות במקום לקרוא ל-endpoint הזה עבור כל מזהה.
  • הודעות ישנות נמחקות: הודעות שנשלחו, נכשלו, בוטלו או פגו ולא השתנו במשך כ-90 יום מחזירות Unknown message id. כך גם הודעות שעדיין ממתינות בתור 90 יום אחרי שנוצרו או אחרי המועד שאליו תוזמנו, במספר שמנותק או נמחק.
  • אינטגרציות ישנות: השימוש ב-POST /api/v1/msg_status/ עם msg_id בגוף הבקשה הוצא משימוש (deprecated). הוא מחזיר את אותם שדות. הוא גם מקבל GET עם client_id, ‏api_key ו-msg_id ב-query string, מה שחושף את מפתח ה-API שלכם בכתובות URL ובלוגים. עברו ל-endpoint הזה.