API الرسائل
API إرسال رسالة
أرسل نصًا أو صورة أو مستندًا عبر WhatsApp إلى رقم هاتف واحد من رقم WhatsApp المتصل الخاص بك. استخدمه لتأكيدات الطلبات، وتذكيرات الدفع، والتنبيهات، وردود الدعم.
https://wbiztool.com/api/v1/send_msg/النص (Body): 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).
api_keystringمطلوبمفتاح API الخاص بك من الصفحة نفسها.
whatsapp_clientintegerمطلوب إذا كان لديك أكثر من رقممعرّف رقم WhatsApp الذي ستُرسَل منه الرسالة، من إعدادات WhatsApp. إذا حذفته وكان في مساحة العمل الخاصة بك رقم متصل واحد فقط، فسيُستخدم ذلك الرقم.
المستلم والرسالة
phonestringمطلوبرقم WhatsApp الخاص بالمستلم، أرقام فقط. تُزال المسافات و
+و-و.والأقواس تلقائيًا. أرسل الرقم إمّا مع رمز الدولة (919876543210) أو بدونه (9876543210) معcountry_code. مع حقول النموذج، لا تضع الصفر البادئ (trunk0) في أول الرقم (09876543210): فهو لا يُزال قبل إضافةcountry_code، فتذهب الرسالة إلى رقم خاطئ. أما طلبات JSON فتُزيله تلقائيًا.country_codestringاختياريرمز الاتصال الدولي للدولة بدون
+، مثل91للهند أو1للولايات المتحدة. يُضاف قبلphoneإلا إذا كان الرقم يبدأ به بالفعل. استثناء: مع91، يحصل الرقم المكوّن من 10 أرقام على البادئة دائمًا. ومع الرموز الأخرى، لا تُضاف البادئة إلى الرقم المحلي الذي يبدأ بالأرقام نفسها، لذا أرسله متضمنًا رمز الدولة.msg_typeintegerاختياري
0نص (افتراضي)، و1صورة، و2ملف أو مستند.msgstringمطلوب عندما تكون قيمة msg_type هي 0نص الرسالة، حتى 3,000 حرف. للصور والملفات يكون هو التعليق (caption) ويمكن أن يكون فارغًا. يعمل تنسيق 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 عمليات إعادة توجيه كحد أقصى، ويجب أن تؤدي كل واحدة منها أيضًا إلى عنوان عام. - يمكن أن يصل حجم الملفات المرتبطة إلى 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 نقطة النهاية هذه نيابةً عنك.
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. استخدم \n للأسطر الجديدة. |
قد تفشل الرسالة الموجودة في قائمة الانتظار عند إرسالها رغم ذلك، مثلًا مع File exceeds WhatsApp size limit (…). هذه الأخطاء لا تظهر أبدًا في هذه الاستجابة. راجع إرسال الصور والملفات وتحقّق من حالة الرسالة.
Webhook#
إذا مرّرت webhook، يرسل Wbiztool طلب POST إلى عنوان URL هذا عند إرسال الرسالة أو فشلها. يكون الجسم مرمّزًا كنموذج (application/x-www-form-urlencoded)، وليس JSON:
msg_id=9817263&status=SENT
| الحقل | القيم |
|---|---|
msg_id | قيمة msg_id التي أُرجعت عند إرسال الرسالة. |
status | SENT أو FAILED |
استجب بأي رمز 2xx. إذا انتهت مهلة نقطة النهاية لديك (بعد 3 ثوانٍ) أو أرجعت 5xx، يُعاد الاستدعاء حتى 3 مرات إجمالًا. لا يُعاد الاستدعاء عند استجابة 4xx. لا يُرسَل أي webhook عند إلغاء رسالة أو انتهاء صلاحيتها؛ استخدم حالة الرسالة لهذه الحالات.
نصائح#
- أرقام الهواتف: خزّن الأرقام بالصيغة الدولية وأرسلها مع
country_codeلتجنّب الالتباس. - الأسطر الجديدة في JSON: اكتبها بالشكل
\nداخلmsg. السطر الجديد الخام يجعل JSON غير صالح. - أبقِ رقمك متصلًا: تُرسَل الرسائل من رقم WhatsApp الخاص بك، لذا يجب أن يبقى متصلًا في إعدادات WhatsApp.
- مستلمون كثيرون: لإرسال الرسالة نفسها إلى عدة أرقام في طلب واحد، استخدم الإرسال إلى عدة أرقام. وللحملات الكبيرة، ارفع جدول بيانات من صفحة الحملات بدلًا من ذلك.
