انتقل إلى المحتوى
WbizTool

API الرسائل

API إرسال رسالة

أرسل نصًا أو صورة أو مستندًا عبر WhatsApp إلى رقم هاتف واحد من رقم WhatsApp المتصل الخاص بك. استخدمه لتأكيدات الطلبات، وتذكيرات الدفع، والتنبيهات، وردود الدعم.

POSThttps://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 "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."
  }'

استبدل YOUR_API_KEY و678 بمفتاحك ومعرّف رقمك. راجع المصادقة لمعرفة مكان العثور عليهما. يوضع المفتاح في ترويسة Authorization: Bearer (موصى به)؛ ويعمل أيضًا client_id وapi_key في الجسم، بصيغة JSON أو كحقول نموذج – وتستخدمهما الأمثلة اللاحقة.

معاملات الطلب#

المصادقة

Authorizationheaderموصى به

‏Bearer YOUR_API_KEY: مفتاح API الخاص بك من Settings → API keys (الإعدادات ← مفاتيح API). مع الترويسة، يمكن حذف 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 المتصل الوحيد. وعندما لا يكون أي رقم WhatsApp متصلًا، يُستخدم رقم إضافة Chrome الوحيد الذي متصفحه مغلق، فتنتظر الرسالة بدلًا من أن تفشل.

المستلم والرسالة

phonestringمطلوب

رقم WhatsApp الخاص بالمستلم. تُزال المسافات و+ و- و. والأقواس و00 البادئة تلقائيًا، لذا يعمل ‎+91 98765-43210. وتُقرأ قيم جداول البيانات مثل 919876543210.0 و9.19876543210E+11 كخاناتها، أما القيمة المقرَّبة مثل 9.19877E+11 فتُرفض، لأن بعض الخانات مفقودة. أرسل الرقم إمّا مع رمز الدولة (919876543210) أو بدونه (9876543210) مع country_code. ويعمل أيضًا الرقم المحلي المكتوب مع الصفر البادئ: يذهب 09876543210 مع country_code 91 إلى 919876543210، ويذهب 0612345678 مع 39 (إيطاليا، حيث الصفر جزء من الرقم) إلى 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 حرف. للصور والملفات يكون هو التعليق (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.

idempotency_keystringاختياري

اختياري، حتى 255 حرفًا. لمدة 24 ساعة، إذا أعدت المحاولة بالقيمة نفسها تحصل على الاستجابة الأولى بدلًا من رسالة ثانية. ويمكنك إرساله بدلًا من ذلك في ترويسة Idempotency-Key. راجع إعادة المحاولة بأمان.

إعادة المحاولة بأمان#

بعد انتهاء المهلة أو انقطاع الاتصال لا يمكنك معرفة ما إذا كان طلبك قد وصل، وقد تؤدي إعادة إرساله إلى وصول الرسالة إلى العميل مرتين. لإعادة المحاولة بأمان، أرسل الحقل idempotency_key أو الترويسة Idempotency-Key بقيمة من عندك فريدة لهذه الرسالة، مثل معرّف طلب الشراء أو UUID، واستخدم القيمة نفسها والطلب نفسه عند إعادة المحاولة.

يعمل ذلك مع إرسال رسالة، والإرسال إلى مجموعة، والإرسال إلى عدة أرقام، وجدولة رسالة. لكل مفتاح API قيمه الخاصة، وتُحفظ لمدة 24 ساعة. ومن دون قيمة، أو بقيمة فارغة، يُرسَل كل طلب كالمعتاد.

ما يحدثالاستجابة
الطلب الأول بهذه القيمةالاستجابة العادية.
إعادة المحاولة بعد نجاح الطلبالاستجابة الأولى مرة أخرى، مع الترويسة Idempotent-Replayed: true. ولا تُنشأ رسالة جديدة.
إعادة المحاولة بعد الرفض (status بقيمة 0)يُنفَّذ الطلب من جديد: لا يُحتفَظ بحالات الرفض، لذا يمكنك تصحيح الطلب وإعادة المحاولة بالقيمة نفسها.
إعادة المحاولة بينما لا يزال الطلب الأول قيد التنفيذ‏HTTP 409، وcode بقيمة idempotency_in_progress، مع Retry-After: 1.
القيمة نفسها مع طلب مختلف‏HTTP 409، وcode بقيمة idempotency_key_reused.
قيمة أطول من 255 حرفًا، أو تحتوي على أسطر جديدة‏HTTP 400، وcode بقيمة invalid_idempotency_key.

لا يمنع idempotency_key سوى إنشاء رسالة ثانية من الطلب نفسه. ولا يخبرك بوصول الرسالة إلى WhatsApp: لذلك استخدم webhook أو حالة الرسالة.

إرسال الصور والملفات#

حدود التنزيل لـ img_url وfile_url:

  • يجب أن يكون عنوان URL عامًا: يبدأ بـ http أو https ويمكن الوصول إليه من الإنترنت. تُتبَع 5 عمليات إعادة توجيه كحد أقصى، ويجب أن تؤدي كل واحدة منها أيضًا إلى عنوان عام.
  • يمكن أن يصل حجم الملفات المرتبطة إلى 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 نقطة النهاية هذه نيابةً عنك.

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
}
الحقلالنوعالوصف
statusinteger‏1 إذا دخلت الرسالة قائمة الانتظار، و0 إذا فشل الطلب.
messagestring‏Created عند النجاح، وإلا نص الخطأ.
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 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. استخدم \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 أو CANCELLED (أُلغيت قبل إرسالها: عبر إلغاء رسالة، أو من لوحة التحكم، أو بسبب إزالة رقم WhatsApp الخاص بها أو حملتها) أو EXPIRED (لم تُرسَل قبل انتهاء expire_after_seconds، أو ظلت تنتظر على رقم غير متصل بعد 48 ساعة من موعدها)

كل webhook موقَّع: تتيح لك الترويستان WbizTool-Timestamp وWbizTool-Signature (v1=‎ متبوعًا بقيمة HMAC-SHA256 لـ <timestamp>.<raw body> بسرّ التوقيع الخاص بمساحة عملك) التحقق من أنه جاء من WbizTool. احصل على السرّ وعلى طريقة التحقق بلغتي Python وNode.js في توقيعات webhook؛ وتستمر المستقبِلات التي تتجاهل الترويستين في العمل.

استجب بأي رمز 2xx؛ تُتبَع عمليات إعادة التوجيه (redirects) 3 مرات كحد أقصى. إذا لم تستجب نقطة النهاية لديك خلال 10 ثوانٍ، أو تعذّر الوصول إليها، أو أرجعت 429 أو 5xx، يعيد WbizTool المحاولة بعد 30 ثانية، ثم بعد دقيقة، ثم بعد دقيقتين (4 محاولات إجمالًا). لا تُعاد المحاولة عند استجابات 4xx الأخرى. يجب أن يكون عنوان URL عنوانًا عامًا على الإنترنت: لا يُرسَل webhook إلى عنوان خاص أو محلي (مثل 192.168.x.x أو localhost).

نصائح#

  • أرقام الهواتف: خزّن الأرقام بالصيغة الدولية وأرسلها مع country_code لتجنّب الالتباس.
  • الأسطر الجديدة في JSON: اكتبها بالشكل \n داخل msg. السطر الجديد الخام يجعل JSON غير صالح.
  • أبقِ رقمك متصلًا: تُرسَل الرسائل من رقم WhatsApp الخاص بك، لذا يجب أن يبقى متصلًا في إعدادات WhatsApp.
  • مستلمون كثيرون: لإرسال الرسالة نفسها إلى عدة أرقام في طلب واحد، استخدم الإرسال إلى عدة أرقام. وللحملات الكبيرة، ارفع جدول بيانات من صفحة الحملات بدلًا من ذلك.