API להודעות
ממשק API להיסטוריית הודעות
קבלו רשימה של ההודעות בסביבת העבודה שלכם בטווח תאריכים, עם הסטטוס של כל אחת. השתמשו בו כדי להצליב מה נשלח, לבנות דוחות או למצוא הודעות שנכשלו כדי לשלוח אותן שוב.
https://wbiztool.com/api/v1/report/גוף הבקשה: JSON (נדרש לדפים שאחרי הראשון) או שדות טופס
ההיסטוריה כוללת כל הודעה בסביבת העבודה של מפתח ה-API שלכם, בין אם נשלחה דרך ה-API, דרך לוח הבקרה או בקמפיין. התוצאות מגיעות 200 בכל דף, מהישנה לחדשה. אותם נתונים זמינים גם בדף Reports (דוחות).
דוגמה מהירה#
curl -X POST https://wbiztool.com/api/v1/report/ \
-H "Content-Type: application/json" \
-d '{
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"start_date": "01-09-2026",
"end_date": "08-09-2026",
"page": 1
}'import requests
page = 1
history = []
while True:
response = requests.post(
"https://wbiztool.com/api/v1/report/",
json={
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"start_date": "01-09-2026",
"end_date": "08-09-2026",
"page": page, # must be a JSON number, not a string
},
timeout=60,
)
result = response.json() # read the body even when the HTTP code is 400
if result.get("message") != "Success" or "total" not in result:
print("Failed:", result.get("message", "no message in response"))
break
history.extend(result["history"])
if page * 200 >= result["total"]:
break
page += 1
failed = [m for m in history if m["message_status"] == "Failed"]
print(len(history), "messages,", len(failed), "failed")// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const history = [];
let page = 1;
while (true) {
const response = await fetch("https://wbiztool.com/api/v1/report/", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
client_id: 12345,
api_key: "YOUR_API_KEY",
start_date: "01-09-2026",
end_date: "08-09-2026",
page, // must be a JSON number, not a string
}),
});
const result = await response.json(); // read the body even when the HTTP code is 400
if (result.message !== "Success" || !("total" in result)) {
console.error("Failed:", result.message ?? "no message in response");
break;
}
history.push(...result.history);
if (page * 200 >= result.total) break;
page += 1;
}
const failed = history.filter((m) => m.message_status === "Failed");
console.log(`${history.length} messages, ${failed.length} failed`);<?php
$history = [];
$page = 1;
do {
$ch = curl_init('https://wbiztool.com/api/v1/report/');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'client_id' => 12345,
'api_key' => 'YOUR_API_KEY',
'start_date' => '01-09-2026',
'end_date' => '08-09-2026',
'page' => $page, // an integer, so json_encode sends a number
]),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($result['message'] ?? '') !== 'Success' || !isset($result['total'])) {
echo 'Failed: ' . ($result['message'] ?? 'no message in response');
break;
}
$history = array_merge($history, $result['history']);
$page++;
} while (($page - 1) * 200 < $result['total']);
echo count($history) . ' messages';החליפו את 12345 ו-YOUR_API_KEY בערכים שלכם. בסעיף אימות מוסבר איפה למצוא אותם.
פרמטרי הבקשה#
אימות
client_idintegerחובהמזהה הלקוח שלכם ל-API (API Client ID) מהדף Settings → API keys.
api_keystringחובהמפתח ה-API שלכם מאותו דף.
מסננים
start_datestringחובההיום הראשון שייכלל, בפורמט
DD-MM-YYYY, למשל01-09-2026.end_datestringחובהסוף הטווח, בפורמט
DD-MM-YYYY. היום הזה עצמו לא נכלל. ראו טווח תאריכים.whatsapp_clientintegerאופציונליהחזרת הודעות שנשלחו רק ממספר ה-WhatsApp הזה, לפי המזהה שלו מהדף הגדרות WhatsApp. השמיטו אותו כדי לקבל הודעות מכל המספרים שלכם.
pageintegerאופציונלימספר הדף, החל מ-
1(ברירת המחדל). כל דף מכיל עד 200 הודעות. שלחו אותו כמספר JSON. הערך0או מספר שלילי מחזירים אתtotalעםhistoryריק.
טווח תאריכים#
התאריכים נקראים כחצות בתחילת אותו יום לפי שעון הודו (IST, UTC+5:30), וההודעות מותאמות לפי מועד היצירה שלהן (כניסה לתור או תזמון), ולא לפי מועד השליחה. הטווח מתחיל ב-start_date בשעה 00:00 ומסתיים ב-end_date בשעה 00:00, ולכן:
- הערכים
"start_date": "01-09-2026", "end_date": "08-09-2026"מחזירים את 1 עד 7 בספטמבר. 8 בספטמבר לא נכלל. - כדי לקבל יום אחד, הגדירו את
end_dateליום שאחריו:"start_date": "15-09-2026", "end_date": "16-09-2026". - אם שני התאריכים זהים, לא תקבלו הודעות.
חלוקה לדפים#
כל תגובה מכילה את total, מספר ההודעות בכל הטווח, ועד 200 מהן ב-history. בקשו page 2, 3 וכן הלאה, עד ש-page × 200 גדול או שווה ל-total.
תגובה#
בקשה מוצלחת מחזירה HTTP 200:
{
"message": "Success",
"status": 0,
"total": 3,
"history": [
{ "id": 9817263, "msg_type": "Text", "contact": "919876543210", "message_status": "Sent" },
{ "id": 9817264, "msg_type": "File", "contact": "919812345670", "message_status": "Failed" },
{ "id": 9817265, "msg_type": "Image", "contact": "Sales Team Mumbai", "message_status": "Pending" }
]
}
| שדה | סוג | תיאור |
|---|---|---|
message | string | Success כשהבקשה עבדה, אחרת השגיאה. |
status | integer | תמיד 0. אל תשתמשו בו כדי לזהות הצלחה. |
total | integer | מספר ההודעות בטווח התאריכים בכל הדפים. מופיע רק בהצלחה. |
history | array | עד 200 הודעות בדף הזה, מהישנה לחדשה. ריק כשיש שגיאה. |
history[].id | integer | מזהה ההודעה, זהה ל-msg_id שהוחזר כשהיא נשלחה. |
history[].msg_type | string | Text, Image או File. |
history[].contact | string | מספר הטלפון של הנמען עם קידומת המדינה, או שם הקבוצה בהודעות לקבוצה. |
history[].message_status | string | ראו את הטבלה שלמטה. |
ערכי סטטוס של הודעה#
message_status | משמעות |
|---|---|
Pending | בתור או מתוזמנת, עוד לא נשלחה (סטטוס 0). |
Sent | נשלחה ממספר ה-WhatsApp שלכם (סטטוס 1). |
Delivered | שמור לשימוש עתידי, לא מוחזר כרגע. |
Read | שמור לשימוש עתידי, לא מוחזר כרגע. |
Failed | לא ניתן היה לשלוח אותה, או שהשליחה נקטעה (סטטוס 2). השתמשו ב-סטטוס הודעה כדי לראות את ה-error. |
Cancelled | בוטלה לפני שנשלחה (סטטוס 3). |
Expired | לא נשלחה לפני המועד האחרון שנקבע ב-expire_after_seconds (סטטוס 4). |
סימוני מסירה וקריאה לא מתועדים כרגע, ולכן הודעות שנשלחו תמיד מופיעות כ-Sent. Delivered ו-Read הם ערכים שמורים; אם הם יופיעו אי פעם, התייחסו אליהם כ-Sent.
שגיאות#
שגיאות מחזירות HTTP 200 עם status שמוגדר ל-0, אלא אם צוין אחרת:
{ "message": "Error", "status": 0, "history": [] }
| הודעה | איך לתקן |
|---|---|
Error | start_date או end_date חסרים או לא בפורמט DD-MM-YYYY, גוף ה-JSON לא תקין (לרוב בגלל פסיק מיותר בסוף), או שהבקשה לא הייתה POST. |
Auth Error | שלחו גם client_id וגם api_key. |
Invalid Client Id | שלחו את client_id כמספר. מוחזר עם HTTP 403, בלי history. |
Auth Error: invalid api key | ודאו שהמפתח קיים, לא נמחק ושייך ל-client_id הזה. מוחזר עם HTTP 400, בלי history. |
Demo Account can not access apis | השתמשו בחשבון רגיל. |
טיפים#
- שלפו היסטוריה בטווחים קטנים: יום או שבוע בכל פעם שומרים על מספר קטן של דפים.
- מציאת הודעות שנכשלו: סננו את
historyלפיFailed, ואז קראו ל-סטטוס הודעה עם כלidכדי לראות למה ההודעה נכשלה. לפני שתנסו שוב, בדקו את ה-error: Sending was interrupted and may have been delivered…אומר שייתכן שההודעה כבר אצל הנמען. - הודעות ישנות נמחקות: הודעות שהגיעו לסטטוס סופי ולא השתנו במשך כ-90 יום עשויות להימחק, ואז הן כבר לא יופיעו כאן. כך גם הודעות שעדיין ממתינות בתור 90 יום אחרי שנוצרו או אחרי המועד שאליו תוזמנו, במספר שמנותק או נמחק.
- מעקב בזמן אמת: כדי להגיב כשהודעות נשלחות, העבירו
webhookכששולחים את ההודעה, במקום לבצע polling ל-endpoint הזה.
