API الخاص بـ Mabel للأعمال

الإصدار 1. اربط Mabel بموقع المصلحة أو بنظام CRM أو بتطبيقها.

البداية

في موقع الإدارة، في "API للمطوّرين"، تنشئ مفتاحًا وتحدّد له الصلاحيات. يبدأ المفتاح بـmabel_ ويُعرض مرة واحدة فقط. أرسله مع كل طلب:

Authorization: Bearer mabel_...

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

الصلاحيات

الصلاحيةماذا تتيح
askسؤال Mabel سؤالًا من زبون، فتجيب من معرفة المصلحة
leadsقراءة العملاء المحتملين وإضافة عميل محتمل
appointmentsقراءة المواعيد التي حجزتها Mabel
actionsالسؤال إن كانت العملية مسموحة وفق سياسة المصلحة، والتحقق إن كان المدير قد وافق
summaryالحصول على ملخص آخر 24 ساعة

المسارات

POST /api/v1/ask

سؤال من زبون. يمكن إرسال question واحدًا، أو messages مع المحادثة حتى الآن.

curl -X POST https://YOUR-SERVER/api/v1/ask \
  -H "Authorization: Bearer mabel_..." \
  -d '{"question": "ما هي ساعات العمل؟"}'

{ "reply": "من الأحد إلى الخميس، 8:00 حتى 19:00...", "actions": [] }

GET /api/v1/leads

حتى آخر 200 عميل محتمل، من الأحدث إلى الأقدم.

{ "leads": [ { "id": "aB3x", "at": "2026-10-06T07:40:00Z", "name": "دانة", "phone": "0501234567", "need": "صبغة", "channel": "phone", "consent": true, "called": null, "handled": null } ] }

POST /api/v1/leads

يضيف عميلًا محتملًا. يلزم name أو phone. أمّا consent فتحدّده true فقط إذا وافق الزبون فعلًا على معاودة الاتصال به.

{ "name": "دانة", "phone": "0501234567", "need": "صبغة شعر", "consent": true }

GET /api/v1/appointments

{ "appointments": [ { "id": "Q9s1", "name": "ياعيل", "phone": "0521112222", "when": "غدًا الساعة 10:00", "reason": "تنظيف الجير", "channel": "phone", "status": "confirmed" } ] }

POST /api/v1/actions/check

قبل أن يقوم نظامك بأي شيء باسم المصلحة، يسأل Mabel. الجواب هو allowed, needs_approval (مع requestId) أو blocked. صرف المال لا يكون أبدًا allowed.

{ "action": "give_discount", "detail": "10% لزبون دائم" } { "decision": "needs_approval", "requestId": "k2Jd81xQ" }

POST /api/v1/actions/status

{ "requestId": "k2Jd81xQ" } { "status": "approved", "by": "ميخال" }

GET /api/v1/summary

{ "text": "في آخر 24 ساعة كانت هناك 3 استفسارات من الزبائن...", "counts": { "asks": 3, "leads": 2, ... } }

التنبيهات (webhooks)

في موقع الإدارة تضيف عنوان https وتختار الأحداث. Mabel ترسل POST لكل حدث، ولا تنتظر ردًا.

الحدثمتى
lead.createdدخل عميل محتمل جديد (هاتف، موقع، API أو يدوي)
appointment.confirmedMabel حجزت موعدًا
request.pendingعملية بانتظار موافقة المدير
request.decidedالمدير وافق أو رفض
POST https://your-system/hook x-mabel-signature: 5f2c... (HMAC-SHA256 لجسم الطلب، مع السر الذي حصلت عليه) { "event": "lead.created", "at": "2026-10-06T07:40:00Z", "company": "عيادة ابتسامة", "data": { "id": "aB3x", "name": "دانة", "phone": "0501234567", "need": "تبييض", "channel": "phone", "consent": true } }

التحقق من التوقيع في Node:

const ok = crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex') === req.headers['x-mabel-signature'];

مثال: وكيل ElevenLabs يطلب الإذن من Mabel

يمكن لوكيل صوتي من ElevenLabs أن يعمل وفق سياسة المصلحة: قبل أن يعطي خصمًا أو يحدد شيئًا، يسأل Mabel. في ElevenLabs تضيف للوكيل أداة من نوع Webhook:

الحقلالقيمة
Nameask_mabel_permission
Method · URLPOST https://YOUR-SERVER/api/v1/actions/check
HeadersAuthorization: Bearer mabel_... (كـ Secret في ElevenLabs، مع مفتاح لديه فقط صلاحية actions)
Body parametersaction (مثلًا give_discount), detail

وفي تعليمات الوكيل: "قبل أي خصم أو التزام للزبون، استدعِ ask_mabel_permission. إذا كان الجواب needs_approval، قل للزبون إن الفريق سيوافق ويعاود الاتصال به. إذا كان blocked، لا تفعل ذلك." هكذا يعمل كل وكلاء المصلحة وفق القواعد نفسها، ويُسجَّل كل طلب في سجل Mabel.

الأخطاء والقيود

الرمزمتى
401لا يوجد مفتاح، أو أنه أُلغي
403ليس لدى المفتاح صلاحية لهذا المسار
429أكثر من 60 طلبًا في الدقيقة للمفتاح نفسه
400طلب غير صالح. السبب في الحقل error

كل عملية عبر الـ API تُسجَّل في سجل عمليات المصلحة باسم المفتاح.