البدء

البدء مع Wbiztool API

يتيح لك REST API من Wbiztool أن يرسل برنامجك رسائل WhatsApp من رقم WhatsApp المتصل الخاص بك. استخدمه لإرسال تحديثات الطلبات والتذكيرات والتنبيهات من تطبيقك أو نظام CRM أو موقعك أو أداة الأتمتة التي تستخدمها.

تشرح هذه الصفحة ما يحتاجه كل طلب. لإرسال رسالتك الأولى، انتقل إلى إرسال رسالة.

عنوان URL الأساسي#

جميع نقاط النهاية (endpoints) موجودة تحت:

https://wbiztool.com/api/v1/

تقبل معظم نقاط النهاية طلبات POST. يمكنك إرسال جسم الطلب بصيغة JSON (application/json) أو كحقول نموذج (application/x-www-form-urlencoded). لرفع ملف، استخدم multipart/form-data. تستخدم بعض نقاط النهاية الخاصة بقراءة البيانات GET؛ وتوضّح صفحة كل نقطة نهاية الطريقة التي تستخدمها.

قبل أن تبدأ#

أنشئ حسابًا على wbiztool.com/signup. تتضمن الحسابات الجديدة 50 رسالة مجانية.
اربط رقم WhatsApp. افتح إعدادات WhatsApp، وانقر على زر الربط، ثم امسح رمز QR من تطبيق WhatsApp على هاتفك.
أنشئ مفتاح API. انتقل إلى Settings → API keys (الإعدادات ← مفاتيح API). لا يستطيع إنشاء المفاتيح إلا مالك مساحة العمل. يمكن أن تحتوي كل مساحة عمل على 10 مفاتيح كحد أقصى.

المصادقة#

تستقبل معظم نقاط النهاية بيانات الاعتماد في جسم كل طلب. أما API التحقق من الأرقام فيستخدم بدلًا من ذلك الترويسة Authorization: Bearer، وتشرح صفحاته الطريقة.

client_idintegerمطلوب: معرّف العميل الخاص بك في API ‏(API Client ID)، ويظهر في صفحة Settings → API keys.
api_keystringمطلوب: أحد مفاتيح API الخاصة بك من الصفحة نفسها. احتفظ به سرًّا: أي شخص يملك المفتاح يستطيع إرسال رسائل من أرقامك.
whatsapp_clientintegerمعظم نقاط نهاية الرسائل: معرّف رقم WhatsApp الذي ستُرسَل منه الرسالة، ويظهر في عمود WhatsApp Client ID (معرّف عميل WhatsApp) في صفحة إعدادات WhatsApp. توضّح صفحة كل نقطة نهاية ما إذا كانت تحتاج إليه.

مفتاح API هو الذي يحدّد مساحة العمل التي ينفَّذ عليها الطلب. إذا كنت عضوًا في أكثر من مساحة عمل، فاستخدم مفتاحًا أُنشئ في مساحة العمل التي تريد الإرسال منها.

إذا تسرّب مفتاح، فاحذفه من صفحة مفاتيح API. تتوقف المفاتيح المحذوفة عن العمل فورًا.

طلبك الأول#

يرسل هذا الطلب رسالة نصية من رقمك المتصل. استبدل المعرّفات والمفتاح ورقم الهاتف بقيمك الخاصة.

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

الاستجابة التي تحتوي على "status": 1 ومعها msg_id تعني أن الرسالة دخلت قائمة الانتظار. تشرح صفحة إرسال رسالة كل معامل، وتتضمن أمثلة بلغات Python وNode.js وPHP.

الاستجابات والأخطاء#

كل استجابة هي كائن JSON يحتوي على الحقل status (باستثناء فحص التشغيل /api/v1/status/، الذي يُرجع "status": 200):

القيمة "status": 1 تعني أن الطلب نجح.
القيمة "status": 0 تعني أنه فشل، ويشرح الحقل message السبب.

{ "status": 0, "message": "Auth Error: invalid api key" }

تحقّق من الحقل status، لا من رمز HTTP فقط

بحسب نقطة النهاية، قد يعود الخطأ برمز HTTP 400 أو 403 أو 200. اقرأ دائمًا جسم JSON وتحقّق من status، وتأكد من أن عميل HTTP لديك يحلّل الجسم حتى عندما يكون رمز الاستجابة 400 أو 403. تُرجع نقاط نهاية التذكيرات حاليًا صفحة خطأ بصيغة HTML مع HTTP 500 عند استخدام مفتاح API غير معروف. وتصف بعض نقاط النهاية استجابة JSON الخاصة بها بأنها text/html بدلًا من application/json. حلّل الجسم على أنه JSON أيًّا كان ما تقوله الترويسة Content-Type، واضبط صيغة الاستجابة على JSON في أدوات مثل Make أو n8n.

أخطاء المصادقة الشائعة:

الرسالة	المعنى
`Auth Error`	‏`client_id` أو `api_key` مفقود، أو أن الجسم ليس JSON أو بيانات نموذج صالحة، أو أن الطلب لم يكن `POST`.
`Auth Error - Please send correct API key and Client id`	‏`api_key` مفقود أو فارغ.
`Invalid client id.` أو `Invalid Client Id`	‏`client_id` ليس عددًا صحيحًا (أو مفقود في بعض نقاط النهاية). أرسله كرقم، مثل `12345`.
`Auth Error: invalid api key`	المفتاح غير موجود، أو حُذف، أو لا ينتمي إلى `client_id` هذا.
`Demo Account can not access apis`	لا يمكن للحسابات التجريبية استخدام API.
`Not enough credits`	لم يتبقَّ في باقتك أي رسائل. قم بالترقية أو انتظر دورة الفوترة التالية.

دورة حياة الرسالة#

تدخل الرسائل التي ترسلها عبر API قائمة الانتظار أولًا، ثم تُرسَل من رقم WhatsApp الخاص بك. لكل رسالة إحدى الحالات التالية:

الحالة	الاسم	المعنى
`0`	Created (تم الإنشاء)	في قائمة الانتظار بانتظار الإرسال.
`1`	Sent (تم الإرسال)	أُرسلت من رقم WhatsApp الخاص بك.
`2`	Failed (فشلت)	تعذّر إرسالها، مثلًا لأن الرقم غير مسجّل على WhatsApp.
`3`	Cancelled (أُلغيت)	أُلغيت قبل إرسالها.
`4`	Expired (انتهت صلاحيتها)	لم تُرسَل قبل المهلة المحددة في `expire_after_seconds`.

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

لمتابعة رسالة، احفظ msg_id من الاستجابة، ثم إمّا أن تمرّر عنوان URL في webhook عند إرسالها، أو أن تستدعي حالة الرسالة.

مكتبات العملاء الرسمية#

تتولى المكتبات المغلِّفة لـ Python وNode.js المصادقة ورفع الملفات نيابةً عنك. لكنها لا تغطي كل نقاط النهاية بشكل صحيح بعد، لذا راجع صفحة كل نقطة نهاية قبل أن تعتمد على أي دالة في المكتبة.

pip install wbiztool-client

npm install wbiztool-client

لـ Python: ‏wbiztool-client على PyPI
لـ Node.js: ‏wbiztool-client على npm

تفضّل إعدادًا بدون برمجة؟ راجع التطبيقات والتكاملات لـ Zapier وn8n وMake وPabbly Connect وGoogle Sheets وShopify وWordPress.

تصفّح التوثيق#

أدلة المنتج: استخدام لوحة تحكم Wbiztool، من ربط رقم إلى الحملات والتذكيرات وUnibox.
API الرسائل: إرسال الرسائل وجدولتها وإلغاؤها وتتبّعها.
API حسابات WhatsApp: ربط الأرقام والتحقق من حالتها.
API التحقق من الأرقام: التحقق دفعة واحدة من الأرقام المسجّلة على WhatsApp.
API التذكيرات: إنشاء التذكيرات المتكررة وعرضها وإلغاؤها.
API الوسائط: رفع الملفات ثم عرضها أو جلبها.
التكاملات: إعدادات بدون برمجة وإضافات.