דלגו לתוכן
WbizTool

API להודעות

ממשק API לשליחת הודעה

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

POSThttps://wbiztool.com/api/v1/send_msg/

גוף הבקשה: JSON, שדות טופס, או multipart/form-data בהעלאת קובץ

ההודעה נכנסת לתור ונשלחת ממספר ה-WhatsApp שלכם תוך רגעים. התגובה מחזירה msg_id שבעזרתו אפשר לבדוק את הסטטוס שלה.

דוגמה מהירה#

curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "whatsapp_client": 678,
    "msg_type": 0,
    "country_code": "91",
    "phone": "9876543210",
    "msg": "Hi Aman, your order #4821 has shipped and will arrive on Thursday."
  }'

החליפו את YOUR_API_KEY ו-678 במפתח ובמזהה המספר שלכם. בסעיף אימות מוסבר איפה למצוא אותם. המפתח נשלח בכותרת Authorization: Bearer (מומלץ); גם client_id ו-api_key בגוף, כ-JSON או כשדות טופס, עובדים – הדוגמאות בהמשך משתמשות בהם.

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

אימות

Authorizationheaderמומלץ

‏Bearer YOUR_API_KEY: מפתח ה-API שלכם מהדף Settings → API keys. עם הכותרת, אפשר להשמיט את client_id ואת api_key מהגוף; אם המפתח נשלח גם בכותרת וגם בגוף, נעשה שימוש במפתח שבכותרת אם הוא תקף. ראו שליחת המפתח בכותרת.

client_idintegerבלי הכותרת Authorization

מזהה הלקוח שלכם ל-API (API Client ID) מהדף Settings → API keys. לא חובה עם הכותרת; אם תשלחו אותו, הוא חייב להיות של סביבת העבודה של המפתח.

api_keystringבלי הכותרת Authorization

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

whatsapp_clientintegerחובה אם יש לכם יותר ממספר אחד

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

נמען והודעה

phonestringחובה

מספר ה-WhatsApp של הנמען. רווחים, +, -, ., סוגריים ו-00 מוביל מוסרים בשבילכם, כך ש-‎+91 98765-43210 עובד. ערכים מגיליון כמו 919876543210.0 ו-9.19876543210E+11 נקראים כספרות שלהם, אבל ערך מעוגל כמו 9.19877E+11 נדחה, כי חסרות בו ספרות. שלחו את המספר עם קידומת המדינה (919876543210) או בלי קידומת (9876543210) יחד עם country_code. גם מספר מקומי שנכתב עם ה-0 המוביל שלו עובד: 09876543210 עם country_code 91 נשלח אל 919876543210, ו-0612345678 עם 39 (איטליה, שבה ה-0 הוא חלק מהמספר) נשלח אל 390612345678. מספר שנכתב עם + או 00 כולל את קידומת המדינה שלו: country_code לא מתווספת אליו, וה-(0) בסוגריים שאחרי הקידומת מושמט, כך ש-‎+44 (0)20 7946 0018 נשלח אל 442079460018. מחשבון Telegram, ‏phone יכול להיות גם ‎@username, קישור t.me/username או tg:<id>.

country_codestringאופציונלי

קידומת החיוג של המדינה בלי +, למשל 91 להודו או 1 לארה"ב. היא מתווספת לפני phone, אלא אם המספר כבר מתחיל בה או נכתב עם + או 00. יוצא מן הכלל: עם 91, מספר בן 10 ספרות תמיד מקבל את הקידומת. עם קידומות אחרות, מספר מקומי שמתחיל באותן ספרות לא מקבל קידומת, לכן שלחו אותו כשקידומת המדינה כבר כלולה בו.

msg_typeintegerאופציונלי

0 טקסט (ברירת מחדל), 1 תמונה, 2 קובץ או מסמך.

msgstringחובה כש-msg_type הוא 0

טקסט ההודעה, עד 3,000 תווים. בתמונות ובקבצים זה הכיתוב, והוא יכול להיות ריק. עיצוב של WhatsApp עובד: *bold*, _italic_, ~strikethrough~. אפשר להשתמש גם בשם החלופי message.

תמונות וקבצים

img_urlstringחובה כש-msg_type הוא 1 ולא הועלה קובץ

כתובת URL ציבורית של התמונה, ב-http או ב-https.

file_urlstringחובה כש-msg_type הוא 2 ולא הועלה קובץ

כתובת URL ציבורית ב-http או ב-https שממנה אפשר להוריד את הקובץ ישירות.

filefileאופציונלי

העלו את התמונה או הקובץ במקום לתת כתובת URL. שלחו את הבקשה כ-multipart/form-data עם שדה בשם file.

file_namestringאופציונלי

שם הקובץ שהנמען רואה, למשל invoice-4821.pdf. הסיומת שלו קובעת איך הקובץ נשלח, לכן הקפידו לכלול סיומת. הוא נשלח באותיות קטנות, תווים כמו & : ? * $ ; מוחלפים ב-_, והוא נחתך ל-150 תווים. אם לא תשלחו אותו, השם יילקח מכתובת ה-URL או מהקובץ שהועלה.

אפשרויות מסירה

expire_after_secondsintegerאופציונלי

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

webhookstringאופציונלי

כתובת URL שמקבלת בקשת POST כשההודעה נשלחת, נכשלת, מבוטלת או פגה. ראו Webhook.

שליחת תמונות וקבצים#

מגבלות ההורדה של img_url ו-file_url:

  • כתובת ה-URL חייבת להיות ציבורית: http או https, נגישה מהאינטרנט. המערכת עוקבת אחרי עד 5 הפניות (redirects), וגם כל אחת מהן חייבת להוביל לכתובת ציבורית.
  • גודל קבצים מקושרים יכול להגיע עד 100 MB. השרת חייב להתחיל להגיב תוך 45 שניות, ולא להיתקע לזמן ארוך מזה.
  • הקובץ מורד ברגע שאתם קוראים ל-API, כך שקישור שבור נכשל מיד עם Invalid file url.

קבצים שנשלחים עם msg_type 2 שומרים על הסיומות האלה:

קטגוריהסיומות
תמונות‎.jpg, ‏‎.jpeg, ‏‎.jpe, ‏‎.png, ‏‎.gif, ‏‎.webp, ‏‎.bmp
מסמכים‎.pdf, ‏‎.doc, ‏‎.docx, ‏‎.docm, ‏‎.xls, ‏‎.xlsx, ‏‎.xlsm, ‏‎.xlsb, ‏‎.ppt, ‏‎.pptx, ‏‎.pptm, ‏‎.txt, ‏‎.csv
אודיו‎.mp3, ‏‎.mpga, ‏‎.m4a, ‏‎.aac, ‏‎.wav, ‏‎.ogg, ‏‎.oga
וידאו‎.mp4, ‏‎.mov, ‏‎.avi, ‏‎.webm
קבצים דחוסים‎.zip, ‏‎.rar

הבדיקות האלה רצות כשההודעה נשלחת, ולא כשאתם קוראים ל-API, כך שהכשלים מופיעים רק בסטטוס הודעה וב-webhook:

בעיהerror בסטטוס הודעה
תמונה (msg_type 1) מעל 16 MBFile exceeds WhatsApp size limit (16MB max)
סרטון (.mp4, .webm) מעל 64 MB, גם כשהוא נשלח כתמונה (msg_type 1)File exceeds WhatsApp size limit (64MB max)
כל קובץ אחר (msg_type 2) מעל 100 MBFile exceeds WhatsApp size limit (100MB max)
קובץ ריק (0 בייט)The file is empty
קובץ ‎.wav או ‎.ogg שנשלח כתמונה (msg_type 1)File type not supported

אי אפשר לשלוח אודיו WAV ו-OGG כתמונה (msg_type 1). כשהם נשלחים כקובץ (msg_type 2), הם מגיעים כמסמך בשם שלהם, למשל recording.wav. קובצי ‎.mp3, ‏‎.mpga, ‏‎.m4a ו-‎.aac מגיעים כאודיו שמתנגן בצ'אט, ו-msg מגיע אחריהם כהודעת טקסט נפרדת (לאודיו אין כיתוב).

תמונה מכתובת URL
curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "whatsapp_client": 678,
    "msg_type": 1,
    "country_code": "91",
    "phone": "9876543210",
    "img_url": "https://example.com/offers/diwali-sale.jpg",
    "msg": "Our Diwali sale starts today 🎉"
  }'
העלאת קובץ
curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -F client_id=12345 \
  -F api_key=YOUR_API_KEY \
  -F whatsapp_client=678 \
  -F msg_type=2 \
  -F country_code=91 \
  -F phone=9876543210 \
  -F "msg=Your invoice for order #4821 is attached." \
  -F file_name=invoice-4821.pdf \
  -F file=@./invoice-4821.pdf

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

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

from wbiztool_client import WbizToolClient

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

result = client.send_message(
    phone="9876543210",
    country_code="91",
    msg="Hi Aman, your order #4821 has shipped.",
    whatsapp_client=678,
)
print(result)

שגיאות זורקות requests.HTTPError. קראו את הסיבה עם e.response.json()["message"].

תגובה#

בקשה מוצלחת מחזירה HTTP 200:

{
  "status": 1,
  "message": "Created",
  "msg_id": 9817263
}
שדהסוגתיאור
statusinteger1 אם ההודעה נכנסה לתור, 0 אם הבקשה נכשלה.
messagestringCreated בהצלחה, אחרת השגיאה.
msg_idintegerהמזהה של ההודעה שבתור. שמרו אותו כדי לבדוק את הסטטוס בהמשך. מופיע רק בהצלחה.

הערך "status": 1 אומר שההודעה נכנסה לתור, ולא שהיא כבר הגיעה לנמען. השתמשו ב-webhook או ב-סטטוס הודעה כדי לוודא שהיא נשלחה.

שגיאות#

שגיאות מחזירות HTTP 400 עם status שמוגדר ל-0 (ל-Account Disabled אין שדה status):

{ "status": 0, "message": "Msg cant be null" }
הודעהאיך לתקן
Auth Error - Please send correct API key and Client idשלחו api_key שאינו ריק.
Invalid client id.שלחו את client_id כמספר.
Auth Error: invalid api keyודאו שהמפתח קיים, לא נמחק ושייך ל-client_id הזה.
Either phone or group_name parameter is requiredהוסיפו phone.
Please provide either phone OR group_name, not bothהסירו אחד מהם.
Invalid phone numberphone חייב להיות מספר באורך 6–17 ספרות. אסור שיהיו בו אותיות או סימנים אחרים, וגם לא ערך מעוגל מגיליון כמו 9.19877E+11.
Invalid Contact Number "…"אחרי הוספת קידומת המדינה, המספר חייב להיות באורך של 7 עד 15 ספרות.
Msg cant be nullהודעות טקסט (msg_type 0) דורשות msg.
Message length is too longהגבילו את msg ל-3,000 תווים לכל היותר.
Image Url Can't be nullעבור msg_type 1, שלחו img_url או העלו file.
File Url Can't be nullעבור msg_type 2, שלחו file_url או העלו file.
Invalid file url, Can't download / Invalid file urlכתובת ה-URL לא ציבורית, חרגה מזמן ההמתנה, או שהקובץ גדול מ-100 MB.
Invalid whatsapp clientהמזהה whatsapp_client הזה לא נמצא בסביבת העבודה שלכם.
Invalid whatsapp client id.שלחו whatsapp_client. הוא חובה כשלסביבת העבודה שלכם יש יותר ממספר מחובר אחד.
Telegram usernames can only be sent to from a Telegram account: pass its id as whatsapp_client‎@username, קישור t.me או tg:<id> ב-phone דורשים חשבון Telegram כ-whatsapp_client.
Not enough creditsסביבת העבודה בתוכנית החינמית ולא נותרו בה הודעות: תוכניות בתשלום שולחות הודעות ללא הגבלה. ראו כשההודעות נגמרות.
Daily limit reached: a number can send 1,000 messages in 24 hours (fair use). Send the rest tomorrow. (HTTP 429, "code": "daily_limit_reached")המספר הזה קיבל 1,000 הודעות ב-24 השעות האחרונות (שימוש הוגן). התגובה עדיין כוללת את ה-msg_id של ההודעה שנדחתה, שמוצגת כנכשלה. שלחו את השאר מאוחר יותר או ממספר אחר.
Demo Account can not access apisהשתמשו בחשבון רגיל.
Account Disabledהחשבון שלכם מושבת. פנו לתמיכה.
Invalid JSON format: …גוף ה-JSON לא תקין, לרוב בגלל פסיק מיותר בסוף או ירידת שורה בתוך msg שלא עברה escape. השתמשו ב-\n לשורות חדשות.

הודעה שנכנסה לתור עדיין יכולה להיכשל כשהיא נשלחת, למשל עם File exceeds WhatsApp size limit (…). השגיאות האלה אף פעם לא מופיעות בתגובה הזו. ראו שליחת תמונות וקבצים ובדקו בסטטוס הודעה.

Webhook#

אם תעבירו webhook, מערכת WbizTool שולחת בקשת POST לכתובת הזו כשההודעה נשלחת או נכשלת, וגם כשהיא מבוטלת או פגה לפני שנשלחה. הגוף מקודד כטופס (application/x-www-form-urlencoded), ולא כ-JSON:

msg_id=9817263&status=SENT
שדהערכים
msg_idה-msg_id שהוחזר כששלחתם את ההודעה.
statusSENT, FAILED, CANCELLED (בוטלה לפני שנשלחה: באמצעות ביטול הודעה, מלוח הבקרה, או כי מספר ה-WhatsApp שלה או הקמפיין שלה הוסרו) או EXPIRED (לא נשלחה לפני שחלף הזמן ב-expire_after_seconds)

כל webhook חתום: הכותרות WbizTool-Timestamp ו-WbizTool-Signature (v1=‎ ואחריו HMAC-SHA256 של <timestamp>.<raw body> בסוד החתימה של סביבת העבודה שלכם) מאפשרות לכם לוודא שהוא הגיע מ-WbizTool. את הסוד ואת הבדיקה ב-Python וב-Node.js תמצאו בחתימות Webhook; מקבלים שמתעלמים מהכותרות ממשיכים לעבוד.

החזירו כל קוד 2xx; מערכת WbizTool עוקבת אחרי הפניה (redirect) עד 3 פעמים. אם ה-endpoint שלכם לא עונה תוך 10 שניות, לא נגיש, או מחזיר 429 או 5xx, מערכת WbizTool מנסה שוב אחרי 30 שניות, אחרי דקה ואחרי שתי דקות (4 ניסיונות בסך הכול). תגובות 4xx אחרות לא מנוסות שוב. הכתובת חייבת להיות כתובת אינטרנט ציבורית: webhook לכתובת פרטית או מקומית (כמו 192.168.x.x או localhost) לא נשלח.

טיפים#

  • מספרי טלפון: שמרו מספרים בפורמט בינלאומי ושלחו אותם עם country_code כדי למנוע אי-בהירות.
  • שורות חדשות ב-JSON: כתבו אותן כ-\n בתוך msg. ירידת שורה גולמית הופכת את ה-JSON ללא תקין.
  • השאירו את המספר מחובר: ההודעות נשלחות ממספר ה-WhatsApp שלכם, ולכן הוא חייב להישאר מחובר בהגדרות WhatsApp.
  • נמענים רבים: כדי לשלוח את אותה הודעה לכמה מספרים בבקשה אחת, השתמשו ב-שליחה למספרים מרובים. לקמפיינים גדולים, העלו במקום זאת גיליון אלקטרוני מהדף Campaigns (קמפיינים).