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 "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."
}'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": 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: { "Content-Type": "application/json" },
body: JSON.stringify({
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.",
}),
});
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 = [
'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.',
];
$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($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');
}החליפו את 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 MB | File 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 קודם.
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), ויכול להתחיל ב-+. |
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 שהוחזר כששלחתם את ההודעה. |
status | SENT או FAILED |
החזירו כל קוד 2xx. אם ה-endpoint שלכם חורג מזמן ההמתנה (אחרי 3 שניות) או מחזיר 5xx, הקריאה מנוסה שוב, עד 3 פעמים בסך הכול. על תגובת 4xx לא מתבצע ניסיון חוזר. לא נשלח webhook כשהודעה מבוטלת או פגה; במקרים האלה השתמשו ב-סטטוס הודעה.
טיפים#
- מספרי טלפון: שמרו מספרים בפורמט בינלאומי ושלחו אותם עם
country_codeכדי למנוע אי-בהירות. - שורות חדשות ב-JSON: כתבו אותן כ-
\nבתוךmsg. ירידת שורה גולמית הופכת את ה-JSON ללא תקין. - השאירו את המספר מחובר: ההודעות נשלחות ממספר ה-WhatsApp שלכם, ולכן הוא חייב להישאר מחובר בהגדרות WhatsApp.
- נמענים רבים: כדי לשלוח את אותה הודעה לכמה מספרים בבקשה אחת, השתמשו ב-שליחה למספרים מרובים. לקמפיינים גדולים, העלו במקום זאת גיליון אלקטרוני מהדף Campaigns (קמפיינים).
