ابنِ إجراءات واتساب مركزة باستخدام واتسلي

البدء السريع

يستخدم واتسلي أجهزة تتحكم فيها مساحة العمل ومفاتيح API محددة الصلاحيات. يجب أن يكون رقم واتساب متصلاً قبل أن يستطيع نظام خارجي إرسال رسالة.

1. 1

   اربط الرقم

   اربط رقم واتساب الخاص بالشركة من مساحة واتسلي وتأكد من أن حالة الاتصال سليمة.

2. 2

   أنشئ مفتاحاً مخصصاً

   أنشئ بيانات اعتماد للجهاز والإجراء المحددين، وانسخ السر عند ظهوره واحفظه في مدير أسرار.

3. 3

   انسخ عنوان API الأساسي

   استخدم العنوان الظاهر في مساحة واتسلي أو إعدادات التكامل. لا تفترض أن أي مثال أو نطاق قديم صالح لحسابك.

4. 4

   أرسل رسالة اختبار

   استخدم مستلماً تجريبياً مصرحاً لك بمراسلته ونوع رسالة مدعوماً ومعرف عدم تكرار فريداً.

5. 5

   أضف Webhook

   اشترك في أحداث الرسائل والأجهزة التي يحتاجها نظامك وتحقق من توقيع كل طلب قبل معالجته.

المصادقة والصلاحيات

تستخدم طلبات API معرف مفتاح وسراً. يجب أن تخص بيانات الاعتماد تكاملاً واحداً معتمداً وألا تتضمن إلا الصلاحيات التي يحتاجها.

X-Api-Key-ID

المعرف العام لبيانات الاعتماد المرتبطة بالجهاز.

X-Api-Key-Secret

السر الذي ينسخ عند إنشاء المفتاح. احتفظ به خارج الشفرة المصدرية وتطبيقات المتصفح.

messages:send

يسمح بإرسال الرسائل المدعومة عبر الجهاز المختار.

messages:read

يسمح بقراءة المحادثات أو الرسائل المدعومة عندما تكون مفعلة للخطة وبيانات الاعتماد.

device:status

يسمح بفحص حالة اتصال الجهاز المختار.

إرسال رسالة

استخدم نقطة الرسائل للأنواع الصادرة المدعومة. يتحقق واتسلي من ملكية الجهاز والاشتراك والحصص وحدود المعدل وضوابط إساءة الاستخدام قبل قبول الإرسال.

• text — نص عادي.
• media — ملف مدعوم من رابط HTTPS يمكن الوصول إليه مع وصف اختياري.
• template — قالب محفوظ في واتسلي مع متغيرات معتمدة.
• location — خط العرض وخط الطول واسم مكان اختياري.

curl -X POST "$WHATSLY_API_BASE_URL/api/v1/messages/send" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key-ID: <your-api-key-id>" \
  -H "X-Api-Key-Secret: <your-api-key-secret>" \
  -d '{
    "device_id": 1,
    "to": "+966500000000",
    "message_type": "text",
    "text": {
      "body": "Hello from Whatsly"
    },
    "idempotency_key": "order-1001"
  }'

القوالب والمتغيرات

تنشأ القوالب داخل مساحة واتسلي وتستخدم للرسائل التشغيلية المتكررة. تسمح المتغيرات بتخصيص الرسالة من دون إعادة بناء النص لكل طلب.

• تشمل المتغيرات المسماة {name} و{phone_number} و{my_name} و{my_email} و{my_contact_number}.
• تدعم متغيرات API الرقمية القيم من {1} حتى {20}.
• يبقى التكامل مسؤولاً عن القيم الصحيحة ومراجعة إجراء الرسالة النهائي.

{
  "device_id": 1,
  "to": "+966500000000",
  "message_type": "template",
  "template_id": 12,
  "variables": {
    "name": "Ahmed",
    "1": "Order #1001",
    "2": "SAR 250"
  },
  "idempotency_key": "order-1001"
}

استقبال أحداث Webhook الموقعة

تبلغ Webhooks نظاماً معتمداً بالرسائل الواردة ونتائج الإرسال وحالة الجهاز. فعّل أنواع الأحداث التي يحتاجها النظام المستقبل فقط.

message.received

وصلت رسالة واردة مدعومة إلى الرقم المتصل.

message.sent

وصلت الرسالة الصادرة إلى حالة الإرسال المقابلة.

message.failed

فشلت محاولة الإرسال وتحتاج إلى مراجعة.

device.connected

جهاز واتساب المختار متصل.

device.disconnected

اتصال الجهاز لم يعد متاحاً.

device.connection.failed / device.revoked

فشل الاتصال أو ألغي الوصول وقد يحتاج إلى تدخل موظف.

{
  "event_id": "evt_01H...",
  "event_type": "message.received",
  "occurred_at": "2026-06-03T10:00:00Z",
  "tenant_id": 1,
  "device_id": 1,
  "data": {
    "message": {
      "id": 101,
      "direction": "inbound",
      "from_phone": "+966500000000",
      "message_type": "text",
      "body": "Hi, is my order ready?"
    }
  }
}

تكاملات التجارة

تحول تكاملات Shopify وWooCommerce أحداثاً مختارة من المتجر إلى رسائل واتساب تشغيلية، مع بقاء منصة التجارة هي مصدر بيانات الطلب.

WooCommerce

يدعم الملحق المتاح إجراءات مختارة للطلب والدفع والحالة والدفع عند الاستلام والإلغاء والاسترداد.

Shopify

موصل Shopify المستضاف ضمن الوصول المبكر ويدعم إجراءات مختارة للطلبات والدفع والتنفيذ والسلة.

معالجة الأخطاء بوضوح

احفظ معرف الرسالة المستلم وثبت معرف عدم التكرار عند إعادة المحاولة، وتعامل مع حدود المعدل والحصة بوصفها إشارة إلى الإبطاء أو مراجعة التكامل.

401 / 403

تحقق من معرف المفتاح والسر والصلاحيات وملكية الجهاز والخطة وصلاحيات مساحة العمل.

422

تحقق من رقم المستلم والحقول المطلوبة وطول النص ورابط الوسائط ومتغيرات القالب وحالة الجهاز.

429

خفّض معدل الطلبات وراجع ضوابط استخدام الجهاز أو مساحة العمل قبل إعادة المحاولة.