WhatsApp Unofficial وWABA إرسال رسالة API

إرسال WhatsApp عبر API التكامل

نقطة نهاية بدون حالة لإرسال رسائل WhatsApp من تطبيقك أو نظامك باستخدام مفتاح API محلي — لا JWT، لا تدفق تسجيل دخول. مصممة لتكاملات الخلفية، أدوات الأتمتة (Zapier/n8n)، أو webhooks مخصصة.

نظرة عامة

واجهة برمجة التطبيقات (API) للتكامل في cshub هي المسار الخارجي لإرسال رسائل WhatsApp من الخلفية أو أدوات الأتمتة الخاصة بك. تستخدم مفتاح API محلي لكل عمل للمصادقة (يتوافق مع سلوك Laravel في whatscrmhub). هذه النقطة النهائية منفصلة عن النقاط الداخلية المستخدمة من قبل لوحة cshub + التطبيق المحمول.

Base URL

https://api.cshub.id/api/v1

Content-Type

application/json

المصادقة

تستخدم المصادقة مفتاح API محلي داخل جسم الطلب (حقل `api_key`)، وليس في رأس HTTP. كل عمل لديه مفتاح API محلي واحد (UUID) يتم إنشاؤه تلقائيًا عند إنشاء العمل.

لا JWT، لا رؤوس توكن

على عكس نقاط النهاية الداخلية للوحة، فقط ضع `api_key` في الجسم ويقوم الخادم بحل العمل من هناك. اعتبر مفتاح API المحلي الخاص بك مثل كلمة مرور — لا تقم أبداً بإيداعه في مستودعات عامة أو كشفه في كود الواجهة الأمامية.

كيف تحصل على مفتاح API المحلي

قم بتسجيل الدخول إلى لوحة cshub على /app.
افتح الإعدادات → مفتاح API (أو الملف الشخصي → التكامل).
انسخ مفتاح API المحلي. يمكنك إعادة توليده في أي وقت — يصبح المفتاح القديم غير صالح على الفور.

نقطة النهاية

تغطي نقطة نهاية واحدة كل إرسال غير رسمي لرسائل WhatsApp (whatsmeow). اختر method = text للرسائل الحرة، أو method = template لإرسال قالب قمت بتكوينه بالفعل في اللوحة.

POST https://api.cshub.id/api/v1/integration/whatsapp/send-message

المصادقة

مفتاح API المحلي في الجسم (`api_key`)

حدود المعدل

لكل جهاز (يتبع حد الإرسال اليومي للجهاز)

حقول الجسم

الجسم هو JSON. الحقول أدناه تتطابق مع Laravel في whatscrmhub — عند الانتقال من الإصدار الأقدم، شكل الطلب هو نفسه.

Field	Type	Required	الوصف
api_key	string	✅	مفتاح API محلي لكل عمل (UUID). احصل عليه من الإعدادات في لوحة cshub.
phone	string	✅	رقم هاتف المستلم بالتنسيق الدولي بدون "+" (مثل 6281234567890)، أو JID مجموعة عندما يكون `is_group` صحيحًا.
method	string	✅	`text`, `template`
text	string	method=text	نص الرسالة. مطلوب عندما يكون method = text.
template	string	method=template	معرف قالب الرسالة الذي تم إنشاؤه في لوحة cshub. مطلوب عندما يكون method = template.
variables	object	—	كائن `{placeholder: value}` حرفي لاستبدال القالب. مثال: `{"$name":"Budi"}` يستبدل كل `$name` في رسالة القالب بـ "Budi".
device_key	string	يعتمد *	UUID لجهاز WhatsApp الذي سيتم الإرسال منه.
is_group	boolean	—	حدد صحيحًا إذا كان `phone` هو JID مجموعة (مثل 120363...@g.us).

أمثلة الطلب

1. إرسال رسالة نصية بسيطة

cURL

curl -X POST "https://api.cshub.id/api/v1/integration/whatsapp/send-message" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "<LOCAL_API_KEY>",
    "device_key": "<DEVICE_ID>",
    "phone": "6281234567890",
    "method": "text",
    "text": "Halo, makasih udah order ya!"
  }'

2. إرسال قالب مع استبدال متغيرات

cURL

curl -X POST "https://api.cshub.id/api/v1/integration/whatsapp/send-message" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "<LOCAL_API_KEY>",
    "device_key": "<DEVICE_ID>",
    "phone": "6281234567890",
    "method": "template",
    "template": "<TEMPLATE_ID>",
    "variables": {
      "$name": "Pak Budi",
      "$order_id": "INV-20260602-001"
    }
  }'

3. إرسال إلى مجموعة (استخدم JID المجموعة)

cURL

curl -X POST "https://api.cshub.id/api/v1/integration/whatsapp/send-message" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "<LOCAL_API_KEY>",
    "device_key": "<DEVICE_ID>",
    "phone": "120363012345678901@g.us",
    "method": "text",
    "text": "Pengumuman: order minggu ini ditutup pukul 17:00.",
    "is_group": true
  }'

استجابة النجاح (200 OK)

200 OK

{
  "status": true,
  "message": "berhasil mengirim pesan"
}

رموز الخطأ والحلول

Status	السبب	الحل
401	Api Key Cannot be recognized	تحقق من أن api_key صحيح (انسخه مرة أخرى من اللوحة) وأن العمل غير معلق.
401	Device tidak di temukan	تحقق من أن device_key صالح وأن الجهاز نشط. أعد اقتران الجهاز عبر QR/رمز الاقتران في اللوحة إذا لزم الأمر.
401	Template tidak dikenali	تحقق من أن معرف القالب صحيح وينتمي إلى عملك (قائمة القوالب موجودة في اللوحة → البيانات الرئيسية → القوالب).
422	Daily send limit habis	انتظر إعادة التعيين اليومي (00:00 WIB) أو انتقل إلى جهاز آخر. ارفع limit_per_day على الجهاز إذا لزم الأمر.
422	Validation gagal (phone/method/text)	تأكد من أن الهاتف بالتنسيق الدولي بدون "+" وأن الطريقة هي واحدة من text/template.
502	WhatsApp service unavailable	خدمة WhatsApp معطلة. حاول مرة أخرى بعد بضع دقائق أو تحقق من حالة الجهاز في اللوحة.

ملاحظات وحدود

هناك حد للإرسال اليومي لكل جهاز. تجنب إرسال أكثر من ~10 رسائل/ثانية من جهاز واحد لتجنب حظر WhatsApp.
إذا كان عملك لديه `api_device_use = required`، فإن حقل `device_key` إلزامي. مع كونه اختياريًا، يختار الخادم جهازًا نشطًا بناءً على إعداد `whatsapp_sender_notif` (`sequence` / `spin` / `random`).
يستخدم استبدال المتغيرات `str_replace` حرفيًا — يمكن أن تكون العناصر النائبة أي سلسلة (مثل `$name`، `{name}`، `[NAME]`). يجب أن تتطابق تمامًا مع النص داخل رسالة القالب.
قم دائمًا بالتنسيق بدون "+" وبدون مسافات/شرطات. مثال: 6281234567890 (إندونيسيا)، 60123456789 (ماليزيا). بالنسبة للمجموعات، استخدم JID الكامل مع اللاحقة `@g.us`.
نسخة MVP: تحميل الملفات الثنائية عبر multipart/form-data غير مدعوم بعد. لإرسال وسائط، استخدم method=template مع قالب يحتوي بالفعل على صورة تم تكوينها في اللوحة.

واجهة برمجة التطبيقات للتكامل مقابل واجهة برمجة التطبيقات الداخلية للوحة

تحتفظ cshub عمدًا بطريقتين لإرسال الرسائل. واجهة برمجة التطبيقات للتكامل مخصصة للمطورين الخارجيين والأتمتة؛ بينما واجهة برمجة التطبيقات الداخلية تدعم لوحة الويب وتطبيق cshub المحمول. جمهور مختلف، مصادقة مختلفة، شكل استجابة مختلف.

	Integration API	واجهة برمجة التطبيقات الداخلية للوحة
الجمهور	مطورون خلفيون، Zapier، n8n، تكاملات مخصصة	لوحة cshub-fe، تطبيق cshub-mobile
الرابط	/integration/whatsapp/send-message	/app/device/{id}/chats/send
المصادقة	api_key di body	JWT Bearer + X-Business-ID + CSRF
شكل الاستجابة	{status, message}	{success, message, data}

هل أنت مستعد للتكامل؟

قم بتسجيل الدخول إلى لوحة cshub، احصل على مفتاح API المحلي من الإعدادات، وابدأ في إرسال WhatsApp من نظامك.

افتح لوحة cshub عرض الأسعار