API להודעות
ממשק API לשליחת הודעה
שלחו הודעת WhatsApp עם טקסט, תמונה או מסמך למספר טלפון אחד, ממספר ה-WhatsApp המחובר שלכם. השתמשו בו לאישורי הזמנה, תזכורות תשלום, התראות ותשובות תמיכה.
https://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."
}'import requests
response = requests.post(
"https://wbiztool.com/api/v1/send_msg/",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"whatsapp_client": 678,
"msg_type": 0,
"country_code": "91",
"phone": "9876543210",
"msg": "Hi Aman, your order #4821 has shipped and will arrive on Thursday.",
},
timeout=60,
)
result = response.json() # read the body even when the HTTP code is 400
if result.get("status") == 1:
print("Queued with msg_id", result["msg_id"])
else:
print("Failed:", result.get("message"))// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v1/send_msg/", {
method: "POST",
headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
body: JSON.stringify({
whatsapp_client: 678,
msg_type: 0,
country_code: "91",
phone: "9876543210",
msg: "Hi Aman, your order #4821 has shipped and will arrive on Thursday.",
}),
});
const result = await response.json(); // read the body even when the HTTP code is 400
if (result.status === 1) {
console.log("Queued with msg_id", result.msg_id);
} else {
console.error("Failed:", result.message);
}<?php
$payload = [
'whatsapp_client' => 678,
'msg_type' => 0,
'country_code' => '91',
'phone' => '9876543210',
'msg' => 'Hi Aman, your order #4821 has shipped and will arrive on Thursday.',
];
$ch = curl_init('https://wbiztool.com/api/v1/send_msg/');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY', 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($result['status'] ?? 0) === 1) {
echo 'Queued with msg_id ' . $result['msg_id'];
} else {
echo 'Failed: ' . ($result['message'] ?? 'no response');
}החליפו את 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_code91נשלח אל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 MB | File exceeds WhatsApp size limit (16MB max) |
סרטון (.mp4, .webm) מעל 64 MB, גם כשהוא נשלח כתמונה (msg_type 1) | File exceeds WhatsApp size limit (64MB max) |
כל קובץ אחר (msg_type 2) מעל 100 MB | File 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 מגיע אחריהם כהודעת טקסט נפרדת (לאודיו אין כיתוב).
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 🎉"
}'import requests
response = requests.post(
"https://wbiztool.com/api/v1/send_msg/",
json={
"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 🎉",
},
timeout=60,
)
print(response.json())// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v1/send_msg/", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
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 🎉",
}),
});
console.log(await response.json());<?php
$ch = curl_init('https://wbiztool.com/api/v1/send_msg/');
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',
'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 🎉',
]),
CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);
curl_close($ch);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.pdfimport requests
with open("invoice-4821.pdf", "rb") as f:
response = requests.post(
"https://wbiztool.com/api/v1/send_msg/",
data={
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"whatsapp_client": 678,
"msg_type": 2,
"country_code": "91",
"phone": "9876543210",
"msg": "Your invoice for order #4821 is attached.",
"file_name": "invoice-4821.pdf",
},
files={"file": f},
timeout=120,
)
print(response.json())// Node.js 20+ (built-in fetch, FormData and fs.openAsBlob). Save as .mjs to use top-level await.
import { openAsBlob } from "node:fs";
const form = new FormData();
form.append("client_id", "12345");
form.append("api_key", "YOUR_API_KEY");
form.append("whatsapp_client", "678");
form.append("msg_type", "2");
form.append("country_code", "91");
form.append("phone", "9876543210");
form.append("msg", "Your invoice for order #4821 is attached.");
form.append("file_name", "invoice-4821.pdf");
form.append("file", await openAsBlob("./invoice-4821.pdf"), "invoice-4821.pdf");
// Don't set Content-Type yourself; fetch adds the multipart boundary.
const response = await fetch("https://wbiztool.com/api/v1/send_msg/", { method: "POST", body: form });
console.log(await response.json());<?php
$ch = curl_init('https://wbiztool.com/api/v1/send_msg/');
curl_setopt_array($ch, [
CURLOPT_POST => true,
// An array body (not json_encode) makes cURL send multipart/form-data.
CURLOPT_POSTFIELDS => [
'client_id' => 12345,
'api_key' => 'YOUR_API_KEY',
'whatsapp_client' => 678,
'msg_type' => 2,
'country_code' => '91',
'phone' => '9876543210',
'msg' => 'Your invoice for order #4821 is attached.',
'file_name' => 'invoice-4821.pdf',
'file' => new CURLFile('/path/to/invoice-4821.pdf', 'application/pdf', 'invoice-4821.pdf'),
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 120,
]);
echo curl_exec($ch);
curl_close($ch);שימוש בלקוחות הרשמיים#
הלקוחות ל-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"].
const { WbizToolClient } = require("wbiztool-client");
const client = new WbizToolClient({
clientId: 12345,
apiKey: "YOUR_API_KEY",
whatsappClient: 678,
});
(async () => {
// Errors throw, with the API's response in the error message.
const result = await client.sendMessage({
phone: "9876543210",
countryCode: "91",
message: "Hi Aman, your order #4821 has shipped.",
});
console.log(result);
})().catch(console.error);תגובה#
בקשה מוצלחת מחזירה HTTP 200:
{
"status": 1,
"message": "Created",
"msg_id": 9817263
}
| שדה | סוג | תיאור |
|---|---|---|
status | integer | 1 אם ההודעה נכנסה לתור, 0 אם הבקשה נכשלה. |
message | string | Created בהצלחה, אחרת השגיאה. |
msg_id | integer | המזהה של ההודעה שבתור. שמרו אותו כדי לבדוק את הסטטוס בהמשך. מופיע רק בהצלחה. |
הערך "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 number | phone חייב להיות מספר באורך 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 שהוחזר כששלחתם את ההודעה. |
status | SENT, 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 (קמפיינים).
