مكتب التحويل

مكتب التحويل صندوق وارد صغير في لوحة التحكم يستلم فيه فريقك المحادثات التي يحوّلها الوكيل. وهو عن قصد ليس نظام دعم فني متكاملًا: يقوم بالأشياء القليلة التي يحتاجها التحويل، بسرعة، على الحاسوب والجوال. وكل ما يفعله متاح عبر الواجهة البرمجية أيضًا، فتستطيع بناء المسار نفسه داخل أدواتك.

قوائم الانتظار

القائمة	تعرض
يحتاج موظفًا	التحويلات المفتوحة التي لم يستلمها أحد بعد — الأولوية العالية أولًا، ثم الأقدم.
لي	التحويلات التي استلمتها.
كل المفتوحة	كل تحويل مفتوح.
المغلقة	التحويلات المُنهاة والمنتهية مدتها.
الموسومة	المحادثات التي وسمها الوكيل للمراجعة عبر flag_conversation.

صفِّ حسب السبب والوكيل والقناة. وتُفصل تحويلات السؤال الواحد (من طلبات ask، بلا محادثة تُستكمل) تحت مرشّح سؤال واحد، حيث يمكنك إنهاؤها بعد المتابعة عبر قناتك الخاصة.

يتحدث المكتب كل 10 ثوانٍ، ويعرض بإذنك إشعارًا في المتصفح ويُصدر صوتًا حين يأتي ما يحتاج موظفًا. وتأتي أعداد الشارات من GET /v1/handoffs/counts، الذي يعيد {unclaimed, mine, open, flagged}.

عرض المحادثة

• سجل المحادثة كاملًا، بما فيه ملخصات قصيرة للإجراءات التي اتخذها الوكيل؛
• بطاقة التحويل: السبب، وملخص الوكيل، ومن طلب التحويل (الوكيل أو الواجهة البرمجية أو السياسات أو زميل)، وفي حالات المسؤولية القانونية الرد الذي رآه العميل بالضبط؛
• ما تعرفه عن العميل: هل هو موثّق، وexternal_id، والقناة، ولغته؛
• عدّاد تنازلي لانتهاء مدة التحويل.

الإجراءات

الإجراء	ما يحدث	الواجهة البرمجية
استلام	يصبح التحويل لك. أول استلام يفوز؛ والآخرون يتلقون 409 handoff_already_assigned. والاستلام يمدّ المدة.	POST /v1/handoffs/{ho}/assign مع {"assignee": "me"}
رد	تصل رسالتك إلى العميل فورًا — في الودجت، وفي بث الجلسة، وفي ويب هوك message.created. وتمدّ المدة.	POST /v1/sessions/{session}/messages مع {"role": "human_agent", "input": "…"}
ملاحظة داخلية	يراها فريقك فقط؛ ولا تُعرض للعميل ولا للذكاء الاصطناعي أبدًا. وتمدّ المدة.	الطلب نفسه مع "visibility": "internal"
إعادة إلى الذكاء الاصطناعي	يتولى الوكيل المحادثة من جديد، مطّلعًا على ردودك. وتُعطى له ملاحظة اختيارية مرة واحدة سياقًا داخليًا.	POST /v1/handoffs/{ho}/resolve مع {"action": "release", "note": "…"}
إغلاق	يُغلق التحويل والمحادثة. ورسالة جديدة من العميل تعيد فتح المحادثة.	POST /v1/handoffs/{ho}/resolve مع {"action": "close"}
تولّي المحادثة	ادخل إلى محادثة جارية مع الذكاء الاصطناعي قبل أن يطلب الوكيل المساعدة.	POST /v1/sessions/{session}/takeover مع {"summary": "…"}
إعادة الإسناد	يستطيع المسؤولون نقل تحويل مستلَم إلى شخص آخر.	POST /v1/handoffs/{ho}/assign مع {"assignee": "usr_…", "force": true}

الرد العام في محادثة يتولاها الذكاء الاصطناعي يُعدّ تولّيًا للمحادثة: يُنشأ لك تحويل تلقائيًا، فيتوقف الوكيل عن الرد.

عبر الواجهة البرمجية

المسار نفسه من أدواتك، بمفتاح سري يملك النطاق sessions:write:

# Find work: open handoffs, oldest first
curl "https://api.k-agent.kerneltics.com/v1/handoffs?status=open" \
  -H "Authorization: Bearer $KAGENT_API_KEY"

# Reply to the customer on behalf of your team
curl https://api.k-agent.kerneltics.com/v1/sessions/sess_01k6rz4p7h2c9m5x8w3t6v1qbg/messages \
  -H "Authorization: Bearer $KAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role": "human_agent", "input": "أهلًا فهد، معك نورة من خدمة العملاء. أتابع طلبك الآن."}'

# Leave a note for the team
curl https://api.k-agent.kerneltics.com/v1/sessions/sess_01k6rz4p7h2c9m5x8w3t6v1qbg/messages \
  -H "Authorization: Bearer $KAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role": "human_agent", "visibility": "internal", "input": "وصلتنا صورة الزجاجة المكسورة؛ الاستبدال معتمد."}'

# Give the conversation back to the agent
curl https://api.k-agent.kerneltics.com/v1/handoffs/ho_01k6rz6c8e0g2j4m6p8r0t2v4x/resolve \
  -H "Authorization: Bearer $KAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "release", "note": "تُشحن له زجاجة بديلة غدًا؛ أكّد ذلك إن سأل."}'

يصفّي GET /v1/handoffs حسب status وassignee وreason_type وagent وsince. وللتفاعل لحظيًا اشترك بـويب هوك في handoff.requested وmessage.created، أو أبقِ بث أحداث الجلسة مفتوحًا.

التوقيت وانتهاء المدة

• يُبقي التحويلُ الذكاءَ الاصطناعي صامتًا لمدة handoff.ttl_hours (الافتراضي 24). والاستلام وكل رسالة من فريقك يمدّان الموعد إلى «الآن + المدة» على الأقل.
• إذا لم يستلمه أحد خلال handoff.notify.unclaimed_reminder_minutes (الافتراضي 10) يُطلق الحدث handoff.unclaimed — وتُرسل تنبيهات بريدية متى كان البريد مُعدًّا على الخادم.
• عند انتهاء المدة يتلقى العميل رسالتك expire_message ويعود الوكيل للرد؛ ومع on_expire: "close" تُغلق المحادثة بدلًا من ذلك.

من يستطيع استخدام المكتب

دور الدعم (support) مصمم للمكتب: يستطيع قراءة المحادثات والاستلام والرد وكتابة الملاحظات والإعادة والإغلاق، لكنه لا يرى إعدادات الوكيل ولا تتبّع التشغيلات. ويستطيع الملّاك والمسؤولون والمطورون والمحررون استخدام المكتب أيضًا؛ أما المشاهدون فيقرؤون فقط.

التذاكر

بجانب القوائم يسرد تبويب التذاكر التذاكر التي فتحتها أداة الوكيل create_ticket ‏(TKT-<n>). حدّث حالتها عبر PATCH /v1/tickets/{tkt} ‏(open وpending وclosed)، واسردها عبر GET /v1/tickets.