بناء إضافة

الإضافة نقطة نهاية HTTPS تتلقى أحداثًا موقّعة من RolChat، إضافة إلى استدعاءات اختيارية تجريها عائدة إلى RolChat. لا توجد شيفرة لرفعها ولا بيئة تشغيل لاستضافتها داخل RolChat.

1. سجّل الإضافة

في الإعدادات ← الإضافات ← الكتالوج ← مخصصة، أو عبر API:

POST /api/v1/plugins
Authorization: Bearer rcp_…
X-Account-Id: <account uuid>

{
  "plugin_type": "custom",
  "name": "Acme back office",
  "api_key_external": "<key RolChat should use to call you, optional>",
  "webhook_url_outbound": "https://backoffice.acme.com/rolchat",
  "sync_config": {
    "enrich_contacts": true,
    "enrich_companies": true,
    "sync_agent_schedule": false,
    "create_contacts": false
  }
}

تحتوي الاستجابة على معرّف الإضافة وسر webhook، الذي يُعرض مرة واحدة. احفظه؛ فكل حدث يرسله RolChat موقّع به، ويجب أن يكون كل حدث ترسله إلى RolChat موقّعًا به أيضًا.

2. تلقَّ الأحداث من RolChat

يرسل RolChat طلبات POST إلى webhook_url_outbound عندما تتغير الأشياء:

الحدث	متى
chats.conversation.created	تبدأ محادثة
crm.contact.created	تُنشأ جهة اتصال
crm.contact.updated	تتغير جهة اتصال
tickets.ticket.created	تُنشأ تذكرة
tickets.ticket.status_changed	تنتقل تذكرة
marketing.meeting.booked	يُحجز اجتماع
marketing.meeting.cancelled	يُلغى اجتماع

{
  "event": "crm.contact.created",
  "account_id": "…",
  "plugin_id": "…",
  "timestamp": "2026-04-13T14:32:00Z",
  "data": { … }
}

تحقق من التوقيع والحداثة وnonce تمامًا كما هو موضح في Webhooks، وأجب بـ 200 بسرعة، وأزل التكرار حسب معرّف الحدث. عائلات الأحداث الأوسع المتاحة للاشتراكات موجودة في كتالوج الأحداث.

3. أرسل الأحداث إلى RolChat

أرسل إلى نقطة النهاية الواردة لإضافتك، موقّعًا بالسر نفسه:

POST /api/v1/webhooks/plugin/{plugin_id}
Content-Type: application/json
X-RolChat-Timestamp: 1713615825
X-RolChat-Signature: sha256=…
X-RolChat-Nonce: nonce_01HK…

{
  "event": "contact.data_updated",
  "timestamp": "2026-04-13T14:32:00Z",
  "data": {
    "external_id": "acme_user_123",
    "email": "user@company.com",
    "plugin_data": { "role": "Admin", "registered_at": "2024-03-15", "last_login": "2026-04-11" }
  }
}

الاستجابة: { "received": true, "matched_contact_id": "…" }.

الحدث الوارد	ما يفعله RolChat
contact.data_updated	يخزّن plugin_data على جهة الاتصال المطابقة
company.data_updated	يخزّن plugin_data على الشركة المطابقة
contact.created_external	ينشئ جهة اتصال أو يحدّثها
agent.unavailable	يشغّل استراتيجية عدم الإتاحة في نموذج الحجز (إلغاء، إعادة إسناد، عرض فترة جديدة)
agent.available	يُبلغ الوكيل بالاجتماعات المعلّقة

المطابقة. يبحث RolChat عن جهة الاتصال بالبريد الإلكتروني أولًا، ثم بـ external_id الذي خزّنته إضافتك سابقًا. إن لم يُعثر عليها: يُنشأ عميل محتمل إذا كان sync_config.create_contacts مفعّلًا، وإلا يُسجَّل الحدث كغير مطابق.

4. أين تظهر بيانات الإضافة

تعرض بطاقات جهات الاتصال والشركات قسمًا باسم إضافتك يضم الحقول التي أرسلتها، للقراءة فقط، مع وقت آخر تحديث. تُعيد API البيانات نفسها:

GET /api/v1/contacts/{id}
{
  "data": {
    "id": "…",
    "plugin_data": {
      "{plugin_id}": { "plugin_name": "Acme back office", "updated_at": "…", "data": { … } }
    }
  }
}

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

5. واجهة API للإدارة

GET    /api/v1/plugins                      connected plugins
GET    /api/v1/plugins/catalog              catalogue
POST   /api/v1/plugins                      connect
GET    /api/v1/plugins/{id}                 details
PATCH  /api/v1/plugins/{id}                 settings
DELETE /api/v1/plugins/{id}                 remove
POST   /api/v1/plugins/{id}/activate        activate
POST   /api/v1/plugins/{id}/deactivate      pause
POST   /api/v1/plugins/{id}/test            test the external key
POST   /api/v1/plugins/{id}/webhook-secret/rotate    rotate with a 7-day overlap
POST   /api/v1/plugins/{id}/webhook-secret/revoke    revoke immediately
GET    /api/v1/plugins/{id}/events          event log (direction, status, type, dates, cursor)
GET    /api/v1/plugins/{id}/sync-schedule   schedule and last run
PATCH  /api/v1/plugins/{id}/sync-schedule   { enabled, cron, timezone }
POST   /api/v1/plugins/{id}/sync-schedule/trigger    run now (one per 5 minutes)

6. البيان

تعلن الإضافة المنشورة عن نفسها في بيان (manifest): الاسم، والفئة، والنطاقات التي تطلبها، والأحداث التي تشترك فيها، ونموذج إعداداتها، وallowed_source_ips اختياريًا، وrecommended_rotation_days، وتسعيرها إن كانت مدفوعة. يحدد البيان شاشة الربط والمراجعة قبل إدراج إضافة مجتمعية.

الحدود والنظافة التشغيلية

• جسم الطلب الوارد حتى 5 MB؛ والصادر 1 MB افتراضيًا.
• مفاتيح API للإضافات محدودة بـ 300 طلب في الدقيقة؛ وwebhooks الواردة بـ 120 في الدقيقة لكل إضافة.
• الإخفاقات المستمرة في التسليم تعلّم الإضافة كمتدهورة؛ وفشل أكثر من النصف لمدة ساعة يوقفها مؤقتًا ويُبلغ مسؤولي الحساب.
• لا تسجّل سر webhook ولا تعرضه أبدًا. دوّره إذا اشتبهت في تسريبه؛ فنافذة التداخل تعني أن شيئًا لن يتعطل.