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.confirmed | Mabel حجزت موعدًا |
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:
| الحقل | القيمة |
|---|---|
| Name | ask_mabel_permission |
| Method · URL | POST https://YOUR-SERVER/api/v1/actions/check |
| Headers | Authorization: Bearer mabel_... (كـ Secret في ElevenLabs، مع مفتاح لديه فقط صلاحية actions) |
| Body parameters | action (مثلًا give_discount), detail |
وفي تعليمات الوكيل: "قبل أي خصم أو التزام للزبون، استدعِ ask_mabel_permission. إذا كان الجواب needs_approval، قل للزبون إن الفريق سيوافق ويعاود الاتصال به. إذا كان blocked، لا تفعل ذلك." هكذا يعمل كل وكلاء المصلحة وفق القواعد نفسها، ويُسجَّل كل طلب في سجل Mabel.
الأخطاء والقيود
| الرمز | متى |
|---|---|
401 | لا يوجد مفتاح، أو أنه أُلغي |
403 | ليس لدى المفتاح صلاحية لهذا المسار |
429 | أكثر من 60 طلبًا في الدقيقة للمفتاح نفسه |
400 | طلب غير صالح. السبب في الحقل error |
كل عملية عبر الـ API تُسجَّل في سجل عمليات المصلحة باسم المفتاح.