דלגו לתוכן
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 של הנמען, ספרות בלבד. רווחים, +, -, . וסוגריים מוסרים בשבילכם. שלחו את המספר עם קידומת המדינה (919876543210) או בלי קידומת (9876543210) יחד עם country_code. בשדות טופס, אל תכללו 0 מוביל של חיוג מקומי (09876543210): הוא לא מוסר לפני הוספת country_code, ולכן ההודעה תגיע למספר הלא נכון. בבקשות JSON הוא מוסר בשבילכם.

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.

סיומות נתמכות: .pdf, .xlsx, .xls, .txt, .docx, .png, .jpg, .jpeg, .webp, .mp3, .mpga, .m4a, .mp4, .webm.

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

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

אודיו WAV ו-OGG לא נתמך. קובץ .wav שנשלח כקובץ (msg_type 2) לא נדחה, אבל מגיע כ-recording.wav.pdf. המירו אודיו ל-.mp3 או ל-.m4a קודם.

תמונה מכתובת 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), ויכול להתחיל ב-+.
Invalid Contact Number "…"אחרי הוספת קידומת המדינה, המספר חייב להיות באורך של 6 עד 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. הוא חובה כשלסביבת העבודה שלכם יש יותר ממספר מחובר אחד.
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 (קמפיינים).