مرجع المطورين · v1

ابنِ باستخدام SmarticBot API

أرسل الرسائل من هاتف واتساب مرتبط برمز QR، وجدول الحملات، وتحقق من الرموز لمرة واحدة، وتحدث إلى المساعد.

هواتف مرتبطة برمز QR · الواجهة العامة v1

البدء السريع

اربط الهاتف برمز QR من القنوات وفعّل خطة.
من وصول المطورين، أنشئ مفتاحًا عامًا للهاتف. انسخه مرة واحدة واحفظه بأمان. إنشاء مفتاح آخر يلغي السابق دون التأثير على اتصال الهاتف.
أرسل الطلب مع x-api-key. استخدم مفتاح المساعد فقط لمسار /chat.

curl -X POST https://smarticbot.com/api/v1/send-message \
  -H 'x-api-key: YOUR_PUBLIC_PHONE_KEY' \
  -H 'Idempotency-Key: order-2026-001' \
  -H 'Content-Type: application/json' \
  -d '{"number":"967771234567","message":"Hello from SmarticBot"}'

الأرقام في الأمثلة توضيحية: يبدأ رمز اليمن بـ +967 والسعودية بـ +966. استبدلها بأرقام المستلمين المقصودين قبل الإرسال.

تعيد الطلبات المقبولة HTTP 202 ومعرّفًا للاستعلام عبر GET /messages/{id}. القبول لا يضمن التسليم.

قبل البدء بالتكامل

دليل إعداد واتساب برمز QR · دليل إعداد واتساب للأعمال الرسمي

تستخدم الأرقام الصيغة الدولية (8–15 رقمًا) مع علامة + اختيارية. تتطلب واجهات JSON نوع application/json؛ ويستخدم إرسال الوسائط multipart/form-data ويدعم JPEG وPNG وWebP وMP4 حتى 10 ميجابايت.

الحدود: 60 طلبًا في الدقيقة لكل مفتاح API (أو لكل عنوان IP دون مفتاح). إصدار رمز التحقق محدود أيضًا بخمسة طلبات لكل رقم خلال عشر دقائق و30 طلبًا لكل جهاز خلال ساعة. تستهلك رسائل الحملة الحصة عند إرسالها لكل مستلم.

حالات الرسالة هي pending وaccepted وsent وdelivered وread وfailed وunknown. قد يتجاوز المزوّد الحالات الوسيطة ولا تعود الحالة إلى الوراء. قد تصل الرسالة حتى إن كانت النتيجة غير معروفة.

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

رمز التحقق مرتبط بالجهاز والرقم، صالح لخمس دقائق ولمرة واحدة، مع خمس محاولات تحقق كحد أقصى. لا يسجّل الدخول إلى SmarticBot.

ويب هوكس العملاء

متاحة لخطط الهواتف المدفوعة. فعّل عنوان الويب هوك في إعدادات الهاتف، ثم أنشئ سر التوقيع من وصول المطورين. تتضمن الطلبات معرّف الحدث والطابع الزمني وإصدار المفتاح والتوقيع. تحقق من HMAC-SHA256 على الطابع الزمني ثم نقطة ثم نص JSON الأصلي. أزل التكرار باستخدام معرّف الحدث. تحتفظ المحاولات المتكررة بنفس الحمولة والإصدار.

expected = 'sha256=' + HMAC_SHA256(secret, timestamp + '.' + raw_body)

تشمل الأحداث device_status_updated وmessage_status_updated. طلبات المزوّد خاصة؛ ولا توجد واجهة عامة لتحديث الحالة.

الاستجابات والحدود والانتقال

تحتوي استجابة النجاح على success=true وكائن data، ويحتوي الخطأ على success=false مع code وmessage وdetails. التحقق 422؛ المفاتيح الخاطئة 401؛ نفاد رصيد المساعد 402؛ الخطط غير الفعالة 403؛ انقطاع الجهاز أو تضارب التكرار 409؛ حدود المعدل أو الحصة 429؛ رفض المزوّد 502؛ النتائج غير المؤكدة 503.

تُقبل المفاتيح القديمة المرتبطة بهوية المزوّد لمدة لا تتجاوز 30 يومًا بعد الترحيل، ويمكن إلغاؤها مبكرًا. أنشئ مفاتيح عامة منفصلة الآن. أزيلت واجهات تحديث حالة الجهاز والرسالة العامة. المستلمون الآن مصفوفة JSON ووقت الحملة يتطلب منطقة زمنية. لا يُستخدم request_id.

فحص الحالة التشغيلية متاح منفصلًا على /api/health؛ وليس واجهة v1 موثقة بمفتاح العميل.

الرسائل

إرسال نص

POST/api/v1/send-message

حقول الطلب

الحقل	النوع	مطلوب
`number`	string	نعم
`message`	string · max 4096	نعم

حالات HTTP المحتملة

202401409422429502503

حقول بيانات الاستجابة

الحقل	النوع	مطلوب
`id`	string	نعم
`status`	string	نعم
`provider_message_id`	string \| null	نعم

الطلب

curl -X POST https://smarticbot.com/api/v1/send-message \
  -H 'x-api-key: YOUR_PUBLIC_PHONE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "number": "967771234567",
    "message": "Hello from SmarticBot"
}'

استجابة النجاح

{
    "success": true,
    "data": {
        "id": "01J...",
        "status": "accepted",
        "provider_message_id": "ABCD"
    }
}

إرسال صورة أو فيديو

POST/api/v1/send-media

حقول الطلب

الحقل	النوع	مطلوب
`number`	string	نعم
`media`	string	نعم
`caption`	string · max 3500	لا

حالات HTTP المحتملة

202401409422429502503

حقول بيانات الاستجابة

الحقل	النوع	مطلوب
`id`	string	نعم
`status`	string	نعم
`provider_message_id`	string \| null	نعم

الطلب

curl -X POST https://smarticbot.com/api/v1/send-media \
  -H 'x-api-key: YOUR_PUBLIC_PHONE_KEY' \
  -F 'number=967771234567' \
  -F '[email protected]'

استجابة النجاح

{
    "success": true,
    "data": {
        "id": "01J...",
        "status": "accepted",
        "provider_message_id": "ABCD"
    }
}

إرسال استطلاع

POST/api/v1/send-poll-message

حقول الطلب

الحقل	النوع	مطلوب
`number`	string	نعم
`poll_question`	string · max 255	نعم
`poll_options`	array	نعم
`allow_multiple_answers`	boolean	لا

حالات HTTP المحتملة

202401409422429502503

حقول بيانات الاستجابة

الحقل	النوع	مطلوب
`id`	string	نعم
`status`	string	نعم
`provider_message_id`	string \| null	نعم

الطلب

curl -X POST https://smarticbot.com/api/v1/send-poll-message \
  -H 'x-api-key: YOUR_PUBLIC_PHONE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "number": "967771234567",
    "poll_question": "Which day?",
    "poll_options": [
        "Monday",
        "Tuesday"
    ],
    "allow_multiple_answers": false
}'

استجابة النجاح

{
    "success": true,
    "data": {
        "id": "01J...",
        "status": "accepted",
        "provider_message_id": "ABCD"
    }
}

حالة تسليم الرسالة

GET/api/v1/messages/{id}

حالات HTTP المحتملة

200401404

حقول بيانات الاستجابة

الحقل	النوع	مطلوب
`id`	string	نعم
`type`	string	نعم
`status`	string	نعم
`provider_message_id`	string \| null	نعم
`sent_at`	string \| null	نعم
`delivered_at`	string \| null	نعم
`read_at`	string \| null	نعم

الطلب

curl -X GET https://smarticbot.com/api/v1/messages/{id} \
  -H 'x-api-key: YOUR_PUBLIC_PHONE_KEY'

استجابة النجاح

{
    "success": true,
    "data": {
        "id": "01J...",
        "type": "text",
        "status": "delivered",
        "provider_message_id": "ABCD",
        "sent_at": "2026-10-14T10:00:00Z",
        "delivered_at": "2026-10-14T10:00:03Z",
        "read_at": null
    }
}

رموز التحقق

إصدار رمز تحقق

POST/api/v1/send-otp

حالات HTTP المحتملة

202401409422429502503

حقول بيانات الاستجابة

الحقل	النوع	مطلوب
`expires_in_seconds`	integer	نعم

الطلب

curl -X POST https://smarticbot.com/api/v1/send-otp \
  -H 'x-api-key: YOUR_PUBLIC_PHONE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "number": "967771234567"
}'

استجابة النجاح

{
    "success": true,
    "data": {
        "expires_in_seconds": 300
    }
}

التحقق من الرمز واستخدامه

POST/api/v1/verify-otp

حقول الطلب

الحقل	النوع	مطلوب
`number`	string	نعم
`code`	string	نعم

حالات HTTP المحتملة

200401422

حقول بيانات الاستجابة

الحقل	النوع	مطلوب
`verified`	boolean	نعم

الطلب

curl -X POST https://smarticbot.com/api/v1/verify-otp \
  -H 'x-api-key: YOUR_PUBLIC_PHONE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "number": "967771234567",
    "code": "123456"
}'

استجابة النجاح

{
    "success": true,
    "data": {
        "verified": true
    }
}

الحملات

جدولة حملة

POST/api/v1/create-campaign

يُنشأ وقت scheduled_at في المثال بعد سبعة أيام من فتح الصفحة. استبدله بالوقت المستقبلي المطلوب مع فرق التوقيت.

حقول الطلب

الحقل	النوع	مطلوب
`campaign_name`	string · max 255	نعم
`campaign_desc`	string · max 255	لا
`message`	string · max 4096	نعم
`recipients`	array	نعم
`scheduled_at`	string	نعم

حالات HTTP المحتملة

201401409422429

حقول بيانات الاستجابة

الحقل	النوع	مطلوب
`id`	integer	نعم
`status`	string	نعم
`scheduled_at`	string	نعم
`recipient_count`	integer	نعم

الطلب

curl -X POST https://smarticbot.com/api/v1/create-campaign \
  -H 'x-api-key: YOUR_PUBLIC_PHONE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "campaign_name": "Scheduled update",
    "message": "Hello!",
    "recipients": [
        "967771234567",
        "966501234567"
    ],
    "scheduled_at": "2026-10-26T05:52:23+00:00"
}'

استجابة النجاح

{
    "success": true,
    "data": {
        "id": 123,
        "status": "scheduled",
        "scheduled_at": "2026-10-26T05:52:23+00:00",
        "recipient_count": 2
    }
}

تقدم الحملة

GET/api/v1/campaigns/{id}

حالات HTTP المحتملة

200401404

حقول بيانات الاستجابة

الحقل	النوع	مطلوب
`id`	integer	نعم
`status`	string	نعم
`scheduled_at`	string \| null	نعم
`sent_count`	integer	نعم
`failed_count`	integer	نعم
`delivered_count`	integer	نعم
`read_count`	integer	نعم

الطلب

curl -X GET https://smarticbot.com/api/v1/campaigns/{id} \
  -H 'x-api-key: YOUR_PUBLIC_PHONE_KEY'

استجابة النجاح

{
    "success": true,
    "data": {
        "id": 123,
        "status": "running",
        "sent_count": 20,
        "failed_count": 0,
        "delivered_count": 17,
        "read_count": 9
    }
}

الأجهزة

معلومات الجهاز المرتبط

GET/api/v1/device/info

حالات HTTP المحتملة

200401

حقول بيانات الاستجابة

الحقل	النوع	مطلوب
`id`	integer	نعم
`name`	string	نعم
`phone_number`	string	نعم
`status`	string	نعم
`is_active`	boolean	نعم
`last_seen_at`	string \| null	نعم

الطلب

curl -X GET https://smarticbot.com/api/v1/device/info \
  -H 'x-api-key: YOUR_PUBLIC_PHONE_KEY'

استجابة النجاح

{
    "success": true,
    "data": {
        "id": 1,
        "name": "Sales",
        "phone_number": "967771234567",
        "status": "connected",
        "is_active": true,
        "last_seen_at": "2026-10-14T10:00:00Z"
    }
}

المساعد

محادثة مع المساعد

POST/api/v1/chat

لكل مساعد مفتاح API خاص به. يحدد المفتاح في x-api-key المساعد. أعد استخدام session_id للمتابعة؛ تُرسل آخر 10 جولات ناجحة لهذا المساعد وهذه الجلسة خلال 30 يومًا كسياق. استخدم قيمة جديدة لمحادثة جديدة، وأرسل طلبات الجلسة الواحدة بالتسلسل. يستهلك السياق السابق رموز إدخال وقد يزيد الرصيد المستخدم. لا يمكن استخدام مفتاح الهاتف مع هذه الواجهة.

حقول الطلب

الحقل	النوع	مطلوب
`session_id`	string · max 128	نعم
`message`	string · max 4096	نعم

حالات HTTP المحتملة

200401402403409422503

حقول بيانات الاستجابة

الحقل	النوع	مطلوب
`reply`	string	نعم
`tokens`	integer	نعم
`credits_used`	integer	نعم

الطلب

curl -X POST https://smarticbot.com/api/v1/chat \
  -H 'x-api-key: YOUR_PUBLIC_ASSISTANT_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "session_id": "customer-42",
    "message": "What are your opening hours?"
}'

استجابة النجاح

{
    "success": true,
    "data": {
        "reply": "We are open 9–5.",
        "tokens": 120,
        "credits_used": 2
    }
}