דלגו לתוכן
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 "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "whatsapp_client": 678,
    "msg_type": 0,
    "country_code": "91",
    "phone": "9876543210",
    "msg": "Hi Aman, your order #4821 has shipped and will arrive on Thursday."
  }'

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

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

אימות

client_idintegerחובה

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

api_keystringחובה

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

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

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

נמען והודעה

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. אל תכתבו (0) בסוגריים אחרי קידומת המדינה: ‎+44 (0)20 7946 0018 נקרא כ-4402079460018 ונשלח למספר שגוי. כתבו ‎+44 20 7946 0018.

country_codestringאופציונלי

קידומת החיוג של המדינה בלי +, למשל 91 להודו או 1 לארה"ב. היא מתווספת לפני phone, אלא אם המספר כבר מתחיל בה. יוצא מן הכלל: עם 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 "…"אחרי הוספת קידומת המדינה, המספר חייב להיות באורך של 6 עד 15 ספרות. מספר בן 6 ספרות מתקבל, אבל נכשל כשהוא נשלח.
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. הוא חובה כשלסביבת העבודה שלכם יש יותר ממספר מחובר אחד.
Not enough creditsלא נותרו הודעות בחבילה שלכם.
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

החזירו כל קוד 2xx. אם ה-endpoint שלכם חורג מזמן ההמתנה (אחרי 3 שניות) או מחזיר 5xx, הקריאה מנוסה שוב, עד 3 פעמים בסך הכול. על תגובת 4xx לא מתבצע ניסיון חוזר. לא נשלח webhook כשהודעה מבוטלת או פגה; במקרים האלה השתמשו ב-סטטוס הודעה.

טיפים#

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