API להודעות
ממשק API לסטטוס הודעה
בדקו אם הודעה ששלחתם דרך ה-API עדיין בתור, נשלחה או נכשלה. השתמשו בו כדי לוודא שהודעות חשובות יצאו, וכדי לגלות למה הודעה מסוימת לא יצאה.
https://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"
}'import requests
msg_id = 9817263
response = requests.post(
f"https://wbiztool.com/api/v1/message/status/{msg_id}/",
json={
"client_id": 12345,
"api_key": "YOUR_API_KEY",
},
timeout=60,
)
result = response.json() # read the body even when the HTTP code is 400
if result.get("message") == "Unknown message id":
print("No message with this ID in your workspace")
elif "status_text" not in result:
print("Request failed:", result.get("message", "no message in response"))
elif result["status"] == 1:
print("Sent")
elif result["status"] == 2:
print("Failed:", result["error"])
else:
print("Status:", result["status_text"])// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const msgId = 9817263;
const response = await fetch(`https://wbiztool.com/api/v1/message/status/${msgId}/`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
client_id: 12345,
api_key: "YOUR_API_KEY",
}),
});
const result = await response.json(); // read the body even when the HTTP code is 400
if (result.message === "Unknown message id") {
console.log("No message with this ID in your workspace");
} else if (!("status_text" in result)) {
console.error("Request failed:", result.message ?? "no message in response");
} else if (result.status === 1) {
console.log("Sent");
} else if (result.status === 2) {
console.log("Failed:", result.error);
} else {
console.log("Status:", result.status_text);
}<?php
$msgId = 9817263;
$payload = [
'client_id' => 12345,
'api_key' => 'YOUR_API_KEY',
];
$ch = curl_init("https://wbiztool.com/api/v1/message/status/{$msgId}/");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($result['message'] ?? '') === 'Unknown message id') {
echo 'No message with this ID in your workspace';
} elseif (!isset($result['status_text'])) {
echo 'Request failed: ' . ($result['message'] ?? 'no message in response');
} elseif ($result['status'] === 1) {
echo 'Sent';
} elseif ($result['status'] === 2) {
echo 'Failed: ' . $result['error'];
} else {
echo 'Status: ' . $result['status_text'];
}החליפו את 12345 ו-YOUR_API_KEY בערכים שלכם. בסעיף אימות מוסבר איפה למצוא אותם.
פרמטרי הבקשה#
כתובת URL
msg_idintegerחובהמזהה ההודעה, כחלק מהנתיב בכתובת ה-URL. הוא חייב להיות מספר שלם ולהשתייך לסביבת העבודה של מפתח ה-API שלכם.
גוף הבקשה
client_idintegerחובהמזהה הלקוח שלכם ל-API (API Client ID) מהדף Settings → API keys.
api_keystringחובהמפתח ה-API שלכם מאותו דף.
שימוש בלקוח הרשמי#
לקוח ה-Python קורא ל-endpoint הזה בשבילכם.
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"
}
| שדה | סוג | תיאור |
|---|---|---|
status | integer | קוד הסטטוס של ההודעה. ראו את הטבלה שלמטה. |
status_text | string | שם הסטטוס: Created, Sent, Failed, Cancelled או Expired. |
message | string | אותו ערך כמו status_text. |
error | string or null | הסיבה שההודעה נכשלה. השדה תמיד קיים; הוא ריק ("" או null) כשאין שגיאה. |
ערכי סטטוס#
status | status_text | משמעות |
|---|---|---|
0 | Created | בתור או מתוזמנת, ממתינה לשליחה. |
1 | Sent | נשלחה ממספר ה-WhatsApp שלכם. |
2 | Failed | לא ניתן היה לשלוח אותה, או שהשליחה נקטעה. השדה error מסביר למה. אם error הוא Sending was interrupted and may have been delivered. Check WhatsApp before resending., ייתכן שההודעה כבר אצל הנמען, לכן אל תשלחו אותה שוב באופן אוטומטי. |
3 | Cancelled | בוטלה לפני שנשלחה, למשל באמצעות ביטול הודעה. |
4 | Expired | לא נשלחה לפני המועד האחרון שנקבע ב-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 הזה.
