أحداث النظام

أحداث النظام تتيح لنظامك الخلفي إخبار وكيلك الذكي أن شيئاً حدث في العالم الحقيقي — وصلت دفعة، شُحِن طلب، تأكد حجز — وتتيح للوكيل التفاعل داخل محادثة العميل القائمة.

بينما تُشعِر الـ Webhooks أنظمتك بما يحدث داخل Orki، أحداث النظام هي الاتجاه المعاكس: أنظمتك تُشعِر الوكيل.

على امتداد هذا الدليل راح نستخدم نشاطنا التجريبي Balloon Bliss: لما يدفع عميل قيمة طلب بالونات، يطلق نظام الطلبات في المحل حدث payment_received، فتشكر الوكيلة الذكية Bella العميل وتؤكد له الطلب — بدون ما يحتاج العميل يسأل أصلاً.

---

كيف تعمل

1. تعرّف الحدث مرة واحدة في لوحة التحكم (اسمه، وما يجب أن يفعله الوكيل، وما البيانات المرافقة له).
2. يستدعي نظامك الخلفي نقطة نهاية API واحدة كل ما وقع الحدث، مشيراً إلى عميل أو محادثة.
3. يوصّل Orki الحدث إلى الوكيل الذكي اللي يتولى محادثة ذلك العميل، فيتفاعل الوكيل حسب الوضع اللي اخترته.

---

الأوضاع الثلاثة

الوضع	ماذا يحدث	استخدمه لـ
إشعار (Notify)	يقرأ الوكيل الحدث كسياق — لا يراسل العميل.	وسم عميل كـ VIP، أو تسجيل تغيير حالة داخلي يجب أن يتذكره الوكيل.
إشعار ورد (Notify & Respond)	يقرأ الوكيل الحدث ويرد على العميل في المحادثة الجارية.	"استلمنا الدفعة"، "شُحن الطلب — أخبرهم بحفاوة."
إرسال قالب (Template Send)	يرسل قالب واتساب/إنستغرام. إذا كانت نافذة المراسلة ما زالت مفتوحة ووكيل ذكي يتولى المحادثة، يتصرف مثل "إشعار ورد" بدلاً من ذلك.	الوصول للعملاء خارج نافذة المراسلة البالغة 24 ساعة.

---

إنشاء حدث: payment_received

خل نبني مثال Balloon Bliss.

1. اذهب إلى الإعدادات ← أحداث النظام
2. اضغط على إضافة حدث

3. عبِّئ التعريف:

• النوع (Kind) — payment_received. هذا هو المعرّف الثابت اللي يستخدمه نظامك الخلفي. أحرف إنجليزية صغيرة وأرقام وشرطات سفلية فقط، ولا يمكن أن يكون أحد الأسماء المحجوزة للمنصة.

• الوضع — إشعار ورد، لأننا نبي Bella تؤكد الدفعة بشكل استباقي.

• تعليمات الوكيل — ما يجب أن يفعله الوكيل عند إطلاق الحدث. تُعامَل هذه التعليمات كتوجيه موثوق من المنصة، وليس كرسالة من العميل. لـ Balloon Bliss:

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

• المعاملات — القيم المهيكلة اللي يرسلها نظامك الخلفي مع كل إطلاق. أضف order_id وamount، وكلاهما مطلوب. كل معامل يأخذ أيضاً قاعدة حلّ (قيمة ثابتة، أو سمة عميل، أو شرطية) تُستخدم كقيمة احتياطية — القيم اللي تمررها وقت الإطلاق تتقدم عليها دائماً.

4. اضغط على إنشاء.

بعد الحفظ، تعرض صفحة تعديل الحدث مقتطف "كيف تطلق هذا الحدث" جاهزاً للاستخدام، ومعبّأ مسبقاً بمعرّف مساحة العمل ومعرّف التعريف:

---

إطلاق الحدث من نظامك الخلفي

كل ما يلي تسلسل حقيقي شغّال — نفّذه من نظام الطلبات عندك، أو من معالج webhook للدفع، أو حتى من الطرفية مباشرة.

الخطوة 1 — أنشئ رمز API

يتحقق نظامك الخلفي من هويته برمز حساب خدمة:

1. اذهب إلى الإعدادات ← رموز حسابات الخدمة
2. اضغط على إنشاء رمز، وأعطه اسم مستخدم (مثلاً balloon-backend) ودوراً

3. انسخ Client ID وClient Secret — السر يظهر مرة واحدة فقط.

استبدل بيانات الاعتماد برمز bearer (صالح لدقائق معدودة — اجلب رمزاً جديداً لكل دفعة استدعاءات):

TOKEN=$(curl -s -X POST "https://iam.orki.ai/realms/orki/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=svc-<tenant-prefix>-balloon-backend&client_secret=<YOUR_CLIENT_SECRET>" \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

الخطوة 2 — اعثر على العميل

استدعاء الإطلاق يحتاج هدفاً. تعطيه واحداً بالضبط من:

الهدف	متى تستخدمه
chatId	تعرف المحادثة المطلوبة بالضبط.
customerId	تعرف العميل — يختار Orki أحدث محادثة مفتوحة نشطة له.
waId	عملاء واتساب — الاستهداف برقم الهاتف.
instagramUsername	عملاء إنستغرام.

عملاء Balloon Bliss يتواصلون عبر أداة الدردشة في الموقع، فما عندنا رقم هاتف ولا حساب إنستغرام نستهدفه — نبحث عن العميل بالاسم/البريد أولاً:

curl -s "https://app.orki.ai/services/gateway/api/v1/tenants/<TENANT_ID>/customers/?page=1&pageSize=5&search=salim" \
  -H "Authorization: Bearer $TOKEN"

تتضمن الاستجابة العميل ومحادثاته:

{
  "data": [
    {
      "id": "6a4b4f14c60e8eabd4e6eed0",
      "name": "Salim Al-Harthy",
      "email": "salim.demo@example.com",
      "platforms": ["web"],
      "platformChats": [
        { "platform": "web", "chatId": "6a4b4f14c60e8eabd4e6eed1" }
      ]
    }
  ]
}

data[0].id هو الـ customerId اللي نحتاجه. في تكامل حقيقي، راح تخزّن هذا المعرّف مقابل سجل العميل في نظامك من أول مرة تشوفه فيها، بدل البحث في كل مرة.

الخطوة 3 — أطلق الحدث

curl -s -X POST "https://app.orki.ai/services/gateway/api/v1/tenants/<TENANT_ID>/system-events/fire" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "definitionId": "<DEFINITION_ID>",
    "customerId": "6a4b4f14c60e8eabd4e6eed0",
    "paramValues": { "order_id": "3", "amount": "1794.85 OMR" }
  }'

الإطلاق الناجح يرجع:

{ "status": "delivered", "mode": 2, "deliveredVia": "agent_request" }

وبعد لحظات تراسل Bella العميل Salim في محادثته على الويب — تشكره، وتؤكد الطلب رقم 5 والدفعة البالغة 35 ر.ع.، وتذكر التوصيل المجاني داخل مسقط.

تقدر أيضاً تضيف سلسلة "contextOverride" لمرة واحدة في المتن — نص إضافي يُلحَق بتعليمات الحدث لهذا الإطلاق فقط.

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

status	المعنى
delivered	وصل الحدث إلى الوكيل (أو أُرسل القالب).
skipped	لم يُوصَّل شيء — يشرح حقل reason السبب (مثلاً لا توجد محادثة مفتوحة للعميل، أو لا يوجد وكيل ذكي يتولى المحادثة، أو استلمها موظف بشري).
failed	حصل خطأ في التوصيل — راجع reason وأعد المحاولة.

---

أفضل الممارسات

• حافظ على ثبات الأنواع (kinds). نظامك الخلفي يكتب النوع/التعريف بشكل ثابت في الكود — عامل إعادة التسمية كتغيير كاسر.
• أطلق بـ customerId ما لم تكن تتتبع معرّفات المحادثات — Orki يختار لك أنسب محادثة مفتوحة للعميل.
• المعاملات المطلوبة هي عقدك. إذا كان نظامك الخلفي ما يقدر يوفر القيمة دائماً، اجعل المعامل اختيارياً وأعطه قيمة احتياطية ثابتة بدلاً من ذلك.
• إشعار أم إشعار ورد؟ إذا كان العميل ما يحتاج يسمع عن الحدث، استخدم "إشعار" فقط — الوكيل يظل متذكراً السياق لبقية المحادثة.
• عطّل، لا تحذف. أطفئ الحدث مؤقتاً وأنت تعدّل تعليماته؛ يستمر نظامك الخلفي في الإطلاق بلا ضرر (الإطلاقات على حدث معطَّل تُتخطى).

استكشاف الأخطاء وحلها

• skipped مع "no chat for target customer" — العميل ما عنده محادثة مفتوحة. لقوالب واتساب خارج النافذة، استخدم وضع "إرسال قالب" بدلاً من ذلك.
• skipped مع "AI is paused" — موظف بشري استلم تلك المحادثة؛ الحدث لن يقاطعه.
• 401 من استدعاء الإطلاق — رموز bearer قصيرة العمر؛ اجلب رمزاً جديداً.
• رد الوكيل يتجاهل معاملاتك — اذكرها في تعليمات الوكيل (مثلاً "أكّد رقم الطلب والمبلغ المدفوع") عشان يعرف النموذج أنها مهمة.

الخطوات التالية

• Webhooks — الاتجاه المعاكس: استلم إشعارات لما تحدث أشياء داخل Orki
• رموز حسابات الخدمة — إدارة الرموز ووثائق API التفاعلية
• مسارات العمل — دع الوكيل يستدعي واجهات API عندك مباشرة