اضغط على Enter.
احصل على بياناتك.

بداية سريعة

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

1. إصدار رمز مميزلوحة المعلومات → رموز API المميزة: الاسم وانتهاء الصلاحية الاختياري والنطاقات التي تحتاجها. ينتمي الرمز المميز إلى عنصر واجهة مستخدم واحد بالضبط. يتم عرض رمز النص العادي مرة واحدة؛ يقوم Smartbtn بتخزين تجزئة أحادية الاتجاه فقط، لذلك لا يمكن استرداد الرمز المفقود - فقط يتم إبطاله وإعادة إصداره.
2. قم بتشغيل واجهة برمجة تطبيقات القطعةفي إعدادات عنصر واجهة المستخدم، قم بتشغيل «السماح بواجهة برمجة تطبيقات عنصر واجهة المستخدم (JS وREST)». لا يؤدي إصدار رمز مميز إلى قلب هذا المفتاح نيابةً عنك.
3. أرسل الطلب الأولينتقل الرمز المميز فقط إلى رأس Authorization - وليس إلى عنوان URL مطلقًا.

# قائمة الدردشات القطعة
curl -H "Authorization: Bearer $SMARTBTN_TOKEN" \
     https://smartbtn.me/api/v1/chats

// 200 OK · ترقيم الصفحات المؤشر
{
  "data": [ { "id": 48211, "status": "open", "last_message_at": "2026-10-17T09:41:12+03:00" }, … ],
  "next_cursor": "eyJpZCI6NDgyMTB9"   // null — في الصفحة الأخيرة
}

المصادقة

ثلاثة مسارات، اعتمادا على من يتصل بمن. يتم رفض الوصول افتراضيًا: لا يوجد نطاق — لا يوجد اتصال.

ينسى الناس التبديل

يؤدي «السماح بواجهة برمجة تطبيقات القطعة (JS وREST)» في إعدادات القطعة إلى فتح كل من REST API وواجهة برمجة تطبيقات القطعة JS. إصدار رمز مميز لا يمكّن من ذلك. يمكن تحرير نطاقات المفتاح الحالي في لوحة المعلومات (رموز واجهة برمجة التطبيقات → المفتاح → تحرير النطاقات) بدون إعادة إصدار - تستمر عمليات التكامل في العمل.

الإعدادات المسبقة

النطاقات

53 نطاقًا للمسار، بالإضافة إلى نطاق مشروط وآخر محجوز. ينجح الطلب فقط إذا كان الرمز المميز يحمل نطاق المسار (أو بديلاً مدرجًا).

نقاط النهاية

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

ترتبط المسارات بـ https://smartbtn.me/api. تحتاج عمليات الكتابة إلى Content‑Type: application/json وX‑Smartbtn‑Idempotency‑Key. مجموعة compat هي طبقة توافق للفرق التي تنتقل من منصة دردشة أخرى.

خطافات الويب

JSON POST مُوقع إلى عنوان URL الخاص بك عند حدوث حدث مشترك. إدارة الاشتراكات عبر /v1/webhook‑subscriptions أو في لوحة التحكم.

{
  "id": "evt_01JAB3K9Q7",
  "type": "ticket.created",
  "data": {
    "button_guid": "b_3f9c2e",
    "ticket_number": 10482,
    "chat_id": 48211,
    "client_id": 9134,
    "reason": "human_request",
    "priority": "high",
    "sla_hours": 4,
    "source": "chat",
    "created_at": "2026-10-17T10:15:00+03:00"
  }
}

رؤوس التسليم

التحقق من التوقيع

HMAC‑SHA256 للنص الخام (البايتات كما تم استلامها، قبل تحليل JSON) مع سر نقطة النهاية الخاصة بك؛ مقارنة في وقت ثابت. يظهر السر مرة واحدة، عند إنشاء الاشتراك؛ قم بتدويرها باستخدام POST /v1/webhook‑subscriptions/{id}/rotate‑secret.

// Node.js · على سبيل المثال، السر هو عنصر نائب
import crypto from 'node:crypto';

function verify(rawBody, header, secret) {
  const expected = 'sha256=v1:' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(header || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// PHP
$expected = 'sha256=v1:' . hash_hmac('sha256', file_get_contents('php://input'), $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_SMARTBTN_SIGNATURE'] ?? '')) { http_response_code(401); exit; }

إعادة المحاولة والنظام

• ما يصل إلى 4 محاولات (الإرسال الأول بالإضافة إلى 3 محاولات إعادة)، والتراجع min(60, 2^attempt × 5) ثانية — حوالي 10، 20، 40 ثانية.
• يتم احتساب غير 2xx أو المهلة كمحاولة فاشلة. يمكن إعادة إرسال عمليات التسليم الفاشلة باستخدام POST /v1/webhook‑subscriptions/{id}/redeliver — نفس مفتاح الكفاءة، ومعرف التسليم الجديد.
• يتم التسليم مرة واحدة على الأقل ولم يتم طلبه. الحمولات ضئيلة - المعرفات، وليست السجلات الكاملة؛ جلب التفاصيل عبر REST API.

JS API

قم بتمرير ما تعرفه بالفعل عن الزائر مباشرة إلى الوكيل. يتم قبول المكالمات فقط من النطاق المحدد في إعدادات القطعة.

smartbtn_widget_api.setContactInfo(info)

يضبط بيانات الاتصال الخاصة بالزائر. يرى الوكيل الأمر كما لو أن الزائر قد ملأ نموذج المقدمة. يلعب الاسم والهاتف والبريد الإلكتروني دورًا خاصًا في Smartbtn، ومن ثم فهي طريقة منفصلة.

Smartbtn_api.setClientInfo({
  name: "أليكس مورغان",
  email: "email@example.com",
  phone: "+17584987855",
  description: "Description text"
});

smartbtn_widget_api.setCustomData(fields)

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

Smartbtn_api.setClientCustomData([
  { title: "Order", content: "#10482 · 3 items", link: "https://shop.example/orders/10482" },
  { title: "Actions", content: "Open customer profile", link: "https://crm.example/c/9134" }
]);

smartbtn_widget_api.setSkin(skin, opts) · open() · close()

قم بتبديل سمة الأداة بسرعة دون إعادة تحميل الصفحة (classic, minimal, capsule, liquid) أو التحكم في نافذة الدردشة برمجيًا. للتخصيص الدائم لكل مشروع، قم بتمرير نفس الحقول إلى PATCH /v1/widget/settings.

// JS API · تبديل الجلد على الصفحة في الوقت الحقيقي
smartbtn_widget_api.setSkin("minimal");
smartbtn_widget_api.setSkin("capsule", { capsuleTitle: "Smartbtn AI", capsuleSubtitle: "الردود خلال ~ 1 ثانية" });

// REST API · PATCH /v1/widget/settings (النطاق widget:write)
{
  "skin": "minimal",
  "widget_header_align": "center",
  "widget_show_operator_avatars": false,
  "widget_show_tabs_bar": false,
  "chat_bg": "#FAF8F5",
  "capsule_title": "Smartbtn AI",
  "capsule_subtitle": "أون لاين 24/7"
}

Support‑agent API

يعمل وكيل الدعم الآلي على قائمة انتظار التذاكر ومحادثات العملاء: يقوم بإجراء محادثة، ويجيب كموظف الدعم البشري الخاص بك، ويغلق التذكرة. متوقف حتى يقوم مالك القطعة بتشغيله.

curl -X POST https://smartbtn.me/api/v1/support/chats/48211/reply \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Smartbtn-Idempotency-Key: $(uuidgen)" \
  -d '{"text":"تم، تمت استعادة الوصول."}'

واجهة برمجة تطبيقات الذكاء الاصطناعي

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

حدود المعدل

لكل رمز مميز، هناك عدادان: يتم حساب عمليات القراءة والكتابة بشكل منفصل، وبالتالي فإن الاقتراع لا يلتهم ميزانية الكتابة أبدًا.

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 12
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0

{ "status": 429, "title": "Too Many Requests", "reason": "rate_limited" }

/v1/ai/assistant/tickets/status و/v1/ai/assistant/account‑link لديهم عدادات خاصة بهم؛ يمكن أن تحتوي واجهة برمجة تطبيقات وكيل الدعم على تجاوز لكل عنصر واجهة مستخدم.

أخطاء

كل خطأ هو RFC‑7807 application/problem+json: حالة وسبب يمكن قراءته بواسطة الآلة، وتفاصيل يمكن قراءتها بواسطة الإنسان.

HTTP/1.1 403 · Content-Type: application/problem+json
{
  "type": "https://smartbtn.me/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Token lacks scope chats:write.",
  "required_scopes": [
    "chats:write"
  ],
  "hint": "Dashboard → API tokens → key → Edit scopes"
}

تسمي الهيئة المطلوبة_النطاقات ومكان منحها. لا حاجة لإعادة إصدار المفتاح.

العجز

الشبكات تفشل. المفتاح يجعل إعادة محاولة الكتابة آمنة: لا يتم تطبيق نفس العملية مرتين أبدًا.

• أرسل X‑Smartbtn‑Idempotency‑Key في كل POST / PATCH / PUT / DELETE: معرف UUID جديد لعملية جديدة، نفس المفتاح لإعادة محاولة نفس العملية.
• العمليات التي تحمل علامة x‑idempotency: Required في OpenAPI: لا يوجد مفتاح → 400، تتم إعادة استخدام المفتاح خلال 24 ساعة → 409 (ليس نجاحاً مخبأً).
• لست متأكدا من أنها مرت؟ اقرأ الدولة أولا. لا تقم أبدًا بتغيير المفتاح تلقائيًا؛ احترام إعادة المحاولة بعد.
• يقوم 502 من موفر الخدمة الأولية بتحرير المفتاح - أعد المحاولة باستخدام نفس المفتاح.

KEY=$(uuidgen)
curl -X PATCH https://smartbtn.me/api/v1/widget/settings \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Smartbtn-Idempotency-Key: $KEY" \
  -d '{"language":"ru"}'
# خطأ في الشبكة؟ كرر بنفس $KEY

Changelog

التغييرات على واجهة برمجة التطبيقات العامة وخطافات الويب في عام 2026. كل شيء أدناه إضافي ويظل في v1.

البرنامج المساعد ووردبريس

القطعة على موقع WordPress دون لمس رمز الموضوع.

عينات التعليمات البرمجية

قم بإدراج كل محادثة مع النشاط منذ آخر استطلاع لك — مع اتباع المؤشر حتى النهاية.

# الصفحة الأولى
curl -G https://smartbtn.me/api/v1/chats \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  --data-urlencode "updated_since=2026-10-17T09:00:00+03:00"

# التالي - مع المؤشر التالي من الاستجابة
curl -G https://smartbtn.me/api/v1/chats \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  --data-urlencode "cursor=eyJpZCI6NDgyMDd9"