דלגו לתוכן
WbizTool

API v2 (בטא)

הודעות

שלחו הודעה עכשיו או במועד שתקבעו, למספר טלפון, לקבוצת WhatsApp, לאיש קשר שמור או לשם משתמש ב-Telegram. שלחו את אותה הודעה לעד 1,000 נמענים בבקשה אחת, קראו את ההיסטוריה, עקבו אחרי הסטטוס של הודעה ובטלו אותה כל עוד היא ממתינה.

פעולהEndpointהרשאה
שליחת הודעהPOST /api/v2/messagesmessages:send
שליחה לנמענים רביםPOST /api/v2/messages/batchmessages:send
רשימת הודעותGET /api/v2/messagesmessages:read
קבלת הודעהGET /api/v2/messages/{id}messages:read
ביטול הודעהDELETE /api/v2/messages/{id}messages:send

מפתחות, שגיאות, Idempotency-Key ומגבלות עובדים כמו שמתואר בסקירה של API v2. כדי לדעת מתי הודעה נשלחת או נכשלת בלי polling, הוסיפו endpoint של Webhook.

שליחת הודעה#

POSThttps://wbiztool.com/api/v2/messages

גוף הבקשה: JSON (application/json)

ההודעה נכנסת לתור והתגובה מגיעה לפני שהיא יוצאת, עם HTTP 202 וה-Message בסטטוס queued (או scheduled עם send_at עתידי). עקבו אחריה עם קבלת הודעה או עם Webhook.

curl -X POST https://wbiztool.com/api/v2/messages \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-ready" \
  -d '{
    "from": 101,
    "to": { "phone": "+919876543210" },
    "text": "Hi Asha, your order #1042 is ready."
  }'

תגובה (202):

{
  "id": 9817263,
  "status": "queued",
  "from": { "id": 101, "phone": "919800000000", "platform": "whatsapp" },
  "to": { "phone": "+919876543210", "contact_id": 991 },
  "text": "Hi Asha, your order #1042 is ready.",
  "media": null,
  "send_at": null,
  "expires_at": null,
  "created_at": "2026-10-18T10:15:02.311Z",
  "sent_at": null,
  "error": null
}

גוף הבקשה

toobjectחובה

מי מקבל אותה: בדיוק אחד מהשדות phone, ‏group, ‏contact_id או username. ראו נמענים.

frominteger or nullחובה, אלא אם בסביבת העבודה יש מספר מחובר אחד

ה-id של המספר ששולח אותה, מרשימת מספרים. אם לא תשלחו אותו, המספר המחובר היחיד ישלח אותה: מספר WhatsApp מחובר אחד ישמש גם אם מחובר גם חשבון Telegram, וחשבון Telegram ישמש רק כשאין מספר WhatsApp מחובר. מספר שהתנתק מתקבל: ההודעות שלו ממתינות עד שהוא מתחבר מחדש.

textstringחובה, אלא אם נשלחת מדיה

ההודעה, עד 3,000 תווים. עם media, זה הכיתוב, ואפשר להשמיט אותו. עיצוב של WhatsApp עובד: *bold*, _italic_, ~strikethrough~. ב-JSON, כתבו שורות חדשות כ-\n.

mediaobject or nullאופציונלי

תמונה או קובץ לשליחה. ראו מדיה.

send_atstring or nullאופציונלי

שליחה במועד הזה במקום עכשיו: ISO 8601 עם ההיסט שלו, למשל 2026-10-20T09:30:00+05:30. המועד חייב להיות בעתיד. ראו תזמון ותפוגה.

expires_atstring or nullאופציונלי

לא לשלוח אחרי המועד הזה: במקום זאת ההודעה הופכת ל-expired. ISO 8601 עם ההיסט שלו, בעתיד ואחרי send_at.

כותרות

Authorizationheaderחובה

‏Bearer wbz_live_…, מפתח עם ההרשאה messages:send.

Idempotency-Keyheaderאופציונלי

מחרוזת ייחודית כלשהי, כדי שניסיון חוזר לעולם לא ישלח הודעה שנייה. ראו Idempotency-Key.

שגיאות בשליחה#

HTTPקודמתי
400validation_failedשדה חסר, מסוג שגוי או לא מוכר; ב-to אין אף אחד מהשדות שלו או שיש כמה; ב-media יש גם url וגם media_id, או אף אחד מהם; ‏expires_at אינו אחרי send_at
400text_requiredאין text ואין media
400text_too_long‏text ארוך מ-3,000 תווים
400invalid_datetime‏send_at או expires_at אינו ISO 8601 עם היסט
402no_creditsלא נותרו לסביבת העבודה הודעות בתוכנית
403number_not_allowedהמפתח מוגבל למספרים אחרים
403account_disabledהחשבון של בעלי סביבת העבודה מושבת
422invalid_phone‏to.phone אינו מספר טלפון בפורמט בינלאומי עם +
422invalid_username‏to.username אינו שם משתמש, קישור או מזהה tg: של Telegram
422username_needs_telegram‏to.username עם מספר WhatsApp כ-from
422contact_not_foundאין איש קשר עם ה-to.contact_id הזה
422media_not_foundאין קובץ עם ה-media.media_id הזה
422invalid_media_url‏media.url אינו קישור http(s) ציבורי
422time_in_pastהמועד של send_at או של expires_at כבר עבר
422number_not_found‏from אינו מספר של סביבת העבודה הזו
422from_requiredאין from, ובסביבת העבודה אין מספר מחובר, או שיש כמה
422message_rejectedלא הצלחנו להכניס את ההודעה לתור; ‏message מסביר למה
429number_daily_cap_reachedהמספר שלח 1,000 הודעות ב-24 השעות האחרונות

שליחה שנדחתה לא משאירה כלום: שום הודעה לא נשמרת, כך שאין מה לבטל. שגיאות שיכולות לקרות בכל בקשה (מפתחות, הרשאות, מגבלות קצב, Idempotency-Key) מופיעות בדף השגיאות.

שליחה לנמענים רבים#

POSThttps://wbiztool.com/api/v2/messages/batch

גוף הבקשה: JSON (application/json)

שולח את אותה הודעה לעד 1,000 נמענים. הגוף זהה לזה של שליחת הודעה, חוץ מזה ש-to הוא רשימה של נמענים.

  • הכול או כלום. כל נמען נבדק לפני ששום דבר נכנס לתור, וכל הרשימה חייבת להיכנס בהודעות שנותרו בתוכנית ובמקום שנותר למספר השולח ב-24 השעות הקרובות. אם נמען אחד שגוי, שום דבר לא נכנס לתור, ו-field מציין אותו, למשל to[3].phone.
  • אותו נמען פעמיים מקבל הודעה אחת.
  • התגובה היא 202 עם data: ‏Message אחד לכל נמען, לפי הסדר של to.
curl -X POST https://wbiztool.com/api/v2/messages/batch \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: opening-hours-2026-10-20" \
  -d '{
    "from": 101,
    "to": [
      { "phone": "+919876543210" },
      { "phone": "+447700900123" },
      { "group": "Bakery staff" }
    ],
    "text": "We open at 10 tomorrow."
  }'

תגובה (202), ‏Message אחד לכל נמען; השני והשלישי נראים כמו הראשון, עם to שמוגדר ל-{"phone": "+447700900123", …} ול-{"group": "Bakery staff", …}:

{
  "data": [
    {
      "id": 9817264,
      "status": "queued",
      "from": { "id": 101, "phone": "919800000000", "platform": "whatsapp" },
      "to": { "phone": "+919876543210", "contact_id": 991 },
      "text": "We open at 10 tomorrow.",
      "media": null,
      "send_at": null,
      "expires_at": null,
      "created_at": "2026-10-19T16:02:40.118Z",
      "sent_at": null,
      "error": null
    }
  ]
}

שגיאות בשליחה מרובה#

אותן שגיאות כמו בשליחת הודעה אחת, עם המיקום של הנמען ב-field (to[0].phone), ובנוסף:

HTTPקודמתי
400too_many_recipientsב-to יש יותר מ-1,000 רשומות
400validation_failed‏to ריק או שאינו רשימה
402no_creditsהרשימה לא נכנסת בהודעות שנותרו: requested ו-remaining מציינים בכמה
429number_daily_cap_reachedהרשימה לא נכנסת במקום שנותר למספר ב-24 השעות הקרובות: requested ו-room מציינים כמה

רשימת הודעות#

GEThttps://wbiztool.com/api/v2/messages

ההודעות של סביבת העבודה מ-90 הימים האחרונים, מהחדשה לישנה, בדפים. הרשימה כוללת הודעות שנשלחו מלוח הבקרה, מקמפיינים, מתזכורות, מאינטגרציות ומ-API v1, ולא רק את אלה של API v2. מפתח שמוגבל לחלק מהמספרים רואה רק את ההודעות שלהם.

פרמטרים של השאילתה

numberintegerאופציונלי

רק הודעות מה-id של המספר הזה.

statusstringאופציונלי

רק הודעות עם הסטטוס הזה: queued, ‏scheduled, ‏sent, ‏delivered, ‏read, ‏failed, ‏cancelled או expired.

sincestringאופציונלי

רק הודעות שנוצרו במועד הזה או אחריו (ISO 8601 עם היסט).

untilstringאופציונלי

רק הודעות שנוצרו לפני המועד הזה (ISO 8601 עם היסט).

limitintegerאופציונלי

הודעות בכל דף, 1 עד 100 (ברירת המחדל 25).

cursorstringאופציונלי

ה-next_cursor של הדף הקודם, עם אותם מסננים.

אפשר לשלב מסננים. במחרוזת שאילתה, כתבו את ה-+ של ההיסט כ-%2B (+ רגיל מגיע כרווח, שגם הוא נקרא כ-+), או השתמשו ב-Z.

curl -G https://wbiztool.com/api/v2/messages \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  --data-urlencode "status=failed" \
  --data-urlencode "since=2026-10-01T00:00:00+05:30" \
  --data-urlencode "limit=100"

התגובה היא {"data": [Message, …], "next_cursor": "…" or null}.

שגיאות ברשימה#

HTTPקודמתי
400validation_failed‏number אינו מזהה של מספר, status אינו אחד מהסטטוסים, או ש-limit אינו בין 1 ל-100
400invalid_datetime‏since או until אינו ISO 8601 עם היסט
400invalid_cursorה-cursor פגום או שנוצר עם מסננים אחרים

קבלת הודעה#

GEThttps://wbiztool.com/api/v2/messages/{id}

הודעה אחת והסטטוס שלה עכשיו.

curl https://wbiztool.com/api/v2/messages/9817263 \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"

תגובה (200), הודעה שנמסרה:

{
  "id": 9817263,
  "status": "delivered",
  "from": { "id": 101, "phone": "919800000000", "platform": "whatsapp" },
  "to": { "phone": "+919876543210", "contact_id": 991 },
  "text": "Hi Asha, your order #1042 is ready.",
  "media": null,
  "send_at": null,
  "expires_at": null,
  "created_at": "2026-10-18T10:15:02.311Z",
  "sent_at": "2026-10-18T10:15:09.870Z",
  "error": null
}

הודעה שלא קיימת, ששייכת לסביבת עבודה אחרת, או (במפתח שמוגבל לחלק מהמספרים) שנשלחה ממספר אחר מחזירה 404 message_not_found.

ביטול הודעה#

DELETEhttps://wbiztool.com/api/v2/messages/{id}

מבטל הודעה שעדיין ממתינה (queued או scheduled), לא משנה מי יצר אותה. התגובה היא 200 עם ה-Message, עכשיו בסטטוס cancelled. ‏endpoint של Webhook מקבל message.cancelled.

אי אפשר להחזיר הודעה שכבר יצאה. הודעה שהמספר השולח אוסף בדיוק באותו רגע עדיין עשויה לצאת, לכן בדקו את הסטטוס שלה אחר כך אם זה חשוב.

curl -X DELETE https://wbiztool.com/api/v2/messages/9817263 \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"

שגיאות בביטול#

HTTPקודמתי
404message_not_foundאין הודעה כזו עבור המפתח הזה
409not_cancellableהיא כבר לא ממתינה; ‏status בשגיאה מציין מה היא עכשיו, למשל sent

האובייקט Message#

כל הפעולות בדף הזה מחזירות אובייקטי Message, ואירועי Webhook נושאים אחד כזה ב-data.message.

שדהסוגתיאור
idintegerהמזהה של ההודעה. השתמשו בו כדי לקבל או לבטל את ההודעה.
statusstringאיפה היא עכשיו. ראו סטטוסים.
fromobjectהמספר השולח: id, ‏phone (הספרות שלו עם קידומת המדינה, בלי +) ו-platform (whatsapp או telegram).
toobjectהנמען: phone (עם +), ‏group או username, ו-contact_id, איש הקשר השמור שאליו היא נשלחה. מספר טלפון או קבוצה שנשלחים אליהם בפעם הראשונה נשמרים כאיש קשר. (‏contact_id הוא null רק בהודעת בדיקה למספר שלא שמור.)
textstringהטקסט או הכיתוב; "" כשאין.
mediaobject or null‏type (image או file), ‏url ו-file_name (null בתמונות). ה-url עשוי להיות קישור שעובד לזמן מוגבל; אל תשמרו אותו.
send_atstring or nullהמועד שאליו היא מתוזמנת, או null ל"עכשיו".
expires_atstring or nullהמועד שאחריו היא לא נשלחת, או null.
created_atstringמתי היא נוצרה.
sent_atstring or nullמתי היא יצאה, אחרי שיצאה (sent, ‏delivered או read).
errorobject or nullבהודעה במצב failed או expired, ‏message מסביר למה, למשל File exceeds WhatsApp size limit (16MB max). אחרת null.

סטטוסים#

סטטוסמשמעות
queuedממתינה ליציאה.
scheduledממתינה ל-send_at שלה.
sentנשלחה מהמספר שלכם (וי אחד ב-WhatsApp).
deliveredנמסרה לטלפון של הנמען (שני וי).
readהנמען קרא אותה (וי כחולים).
failedלא הצלחנו לשלוח אותה; ‏error.message מסביר למה.
cancelledבוטלה לפני שיצאה: עם ביטול הודעה, מלוח הבקרה, או כי המספר או הקמפיין שלה הוסרו.
expiredלא נשלחה לפני ה-expires_at שלה.

אפשר לבטל הודעות במצב queued ו-scheduled. הודעה במצב sent עדיין יכולה להפוך ל-delivered ואז ל-read. ‏failed, ‏cancelled, ‏expired ו-read הם סופיים. ‏Webhooks מדווחים על sent, ‏failed, ‏cancelled ו-expired; כדי לראות delivered ו-read, קבלו את ההודעה.

נמענים#

‏to מקבל בדיוק אחד מהשדות האלה:

שדהדוגמהמי מקבל אותה
phone{"phone": "+919876543210"}מספר טלפון בפורמט בינלאומי עם + (E.164). מותר להשתמש ברווחים ובמקפים.
group{"group": "Bakery staff"}קבוצת WhatsApp שהמספר השולח חבר בה, לפי השם המדויק שלה (עד 200 תווים).
contact_id{"contact_id": 991}איש קשר ששמור בסביבת העבודה, לפי המזהה שלו (למשל ה-contact_id של הודעה קודמת). היא נשלחת למספר או לקבוצה של איש הקשר הזה.
username{"username": "@asha_bakes"}משתמש Telegram: ‏‎@name, קישור t.me/name, או tg: ומזהה משתמש. רק מחשבון Telegram, לכן ציינו חשבון כזה כ-from (או שיהיה מחובר בדיוק חשבון אחד).

שליחות לקבוצות ול-Telegram דורשות שהמספר השולח יהיה חבר באותה קבוצה או יוכל להגיע לאותו משתמש; בעיות כאלה מופיעות כהודעה במצב failed, ולא כשגיאה כשאתם שולחים.

מדיה#

‏media שולח תמונה או קובץ, עם text ככיתוב שלהם. ציינו בדיוק אחד מהשדות url או media_id:

media.urlstringurl או media_id

קישור http או https ציבורי לקובץ, עד 1,000 תווים. קישורים לכתובות פרטיות או מקומיות נדחים עם invalid_media_url.

media.media_idintegerurl או media_id

קובץ בספריית המדיה של סביבת העבודה, מהעלאת קובץ. העלו קובץ פעם אחת ושלחו אותו כמה פעמים שתרצו.

media.typestringאופציונלי

‏image או file. אם לא תשלחו אותו, קישור שמסתיים ב-‎.jpg, ‏‎.jpeg, ‏‎.png, ‏‎.gif או ‎.webp נשלח כתמונה וכל השאר כקובץ; ‏media_id משתמש בסוג שאיתו הקובץ הועלה.

media.file_namestringאופציונלי

ל-file: השם שהנמען רואה, למשל invoice-1042.pdf (עד 100 תווים). אם לא תשלחו אותו, השם יילקח מהקישור או מהקובץ שהועלה. הסיומת שלו קובעת איך הקובץ נשלח, לכן הקפידו לכלול סיומת. בתמונות המערכת מתעלמת ממנו.

{
  "to": { "phone": "+919876543210" },
  "text": "Your invoice for order #1042",
  "media": { "url": "https://example.com/invoices/1042.pdf", "type": "file", "file_name": "invoice-1042.pdf" }
}

הקובץ מורד כשההודעה נשלחת, ולא כשאתם קוראים ל-API, כך שקישור שבור או קובץ גדול מדי מופיעים כהודעה במצב failed עם הסיבה ב-error.message. כללי הגודל והסוג הם אלה של v1: ראו שליחת תמונות וקבצים.

תזמון ותפוגה#

  • send_at מתזמן את ההודעה. היא נשארת scheduled עד אז, ואפשר לבטל אותה עד שהיא יוצאת. כתבו את הזמן עם ההיסט שלו, כך ש-2026-10-20T09:30:00+05:30 פירושו 09:30 בהודו. להודעות שחוזרות על עצמן, השתמשו בתזכורות.
  • expires_at הוא מועד אחרון: אם ההודעה לא יצאה עד אז (למשל כי המספר התנתק), היא הופכת ל-expired במקום לצאת באיחור. השתמשו בו לקודים חד-פעמיים, לזמני משלוח ולמבצעים. תהליך רקע מסמן אותה כפגת תוקף לפחות 30 שניות אחרי המועד האחרון, לכן אל תסתמכו על מועדים קצרים מדקה.
  • שניהם חייבים להיות בעתיד, ו-expires_at חייב להיות אחרי send_at.

מדריכים קשורים#

  • Webhooks: קבלו message.sent ו-message.failed במקום polling.
  • מדיה: העלו קבצים כדי לשלוח אותם לפי media_id.
  • מספרים: ה-id שמשתמשים בו כ-from.
  • שגיאות