كيف أُعدّ خطوتي إجراء التكامل واستدعاء الأداة؟

ما فائدتها؟

تنفّذ الخطوتان عملًا في نظام خارجي عند نقطة من الوكيل، ولا يرى الزائر أيًّا منهما.

• «إجراء تكامل» يشغّل إجراءً جاهزًا من تكامل متصل (مثل إنشاء بطاقة Trello أو إرسال إشعار إلى Slack أو Teams).
• «استدعاء أداة» يستدعي أداة عرّفتها لنظامك في صفحة «الأدوات» (مثل الاستعلام عن حالة طلب).

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

إجراء التكامل

لا يرى الزائر هذه الخطوة: يشغّل المسار هنا إجراءً من تكامل متصل (مثل إنشاء بطاقة Trello أو إرسال إشعار إلى Slack أو Teams) ثم ينتقل إلى الخطوة التالية.

1. افتح فئة «التكاملات» في لوحة «إضافة خطوة»، وانقر على التكامل ثم على الإجراء، فتُضاف الخطوة إلى اللوحة.
2. تحقق من «الإجراء» في لوحة الخطوة واملأ حقوله. اختر القيم من القائمة («اختر من القائمة») أو اكتبها بنفسك («سأكتبها بنفسي»)، واستخدم {variable} للإجابات السابقة.
3. لاستخدام النتيجة لاحقًا امنحها اسم متغير في قسم «حفظ في المتغيرات». تبقى المتغيرات في متصفح الزائر، فلا تختر قيمًا يجب أن تبقى خاصة.

للخطوة مخرجان: «عند الاكتمال» و«إذا فشل». إذا لم يكن التكامل متصلًا أو أعاد المزوّد خطأً ينتقل المسار إلى «إذا فشل». وإذا كان فرع «إذا فشل» فارغًا تُغلق المحادثة برسالة تفيد بحدوث مشكلة. وإن أردت أن يستمر الوكيل عند الفشل أيضًا فاربط «إذا فشل» بالخطوة نفسها التي يقود إليها «عند الاكتمال». وإذا كان حقل إلزامي فارغًا فلا يُستدعى المزوّد أصلًا وتنتقل الخطوة إلى «إذا فشل». «ملاحظة الخطوة» لك وحدك ولا يراها الزائر.

لا يعمل الإجراء الذي يغيّر البيانات مرة أخرى عندما يضغط الزائر زر الرجوع أو يعيد إرسال رسالة. أما إذا مرّت المحادثة بهذه الخطوة من جديد (مثل العودة عبر قائمة) فيعمل مرة أخرى.

أثناء تنفيذ الخطوة يرى الزائر ما يجري بدل «يفكّر»: نصًا مناسبًا («جارٍ تنفيذ طلبك…»، «جارٍ التحقق من المعلومات…»)، وفي الأعمال الداخلية مثل إبلاغ فريقك «لحظة من فضلك…» فقط. يمكنك كتابة نصك في حقل «النص المعروض أثناء الانتظار» (مثل «جارٍ إنشاء موعدك…»)، ويُترجم إلى لغاتك الأخرى.

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

استدعاء أداة

يستدعي أداة عرّفتها في صفحة «الأدوات» عند هذه النقطة بالضبط من الوكيل دون استخدام الذكاء الاصطناعي. لا يرى الزائر هذه الخطوة، ونصها ملاحظة لك فقط.

1. أضف خطوة استدعاء أداة واختر الأداة من القائمة.
2. أعطِ حقول الأداة قيمة: قيمة ثابتة، أو متغيرًا من إجابة سابقة (مثل {order_no})، أو مسار حقل في إجابة سابقة (مثل {order.no}).
3. في «حفظ في المتغيرات» احفظ الرد كاملًا أو رمز الخطأ في متغير، ثم استخدمه في الخطوات اللاحقة بصيغة {variable}.
4. اربط فرعَي «عند الاكتمال» و«إذا فشل». إذا لم ترد الأداة أو أعادت خطأً ينتقل المسار إلى فرع «إذا فشل». وإذا كان فرع «إذا فشل» فارغًا تُغلق المحادثة برسالة تفيد بحدوث مشكلة. وإن أردت أن يستمر الوكيل عند الفشل أيضًا فاربط «إذا فشل» بالخطوة نفسها التي يقود إليها «عند الاكتمال».

أثناء تشغيل الأداة يرى الزائر نصًا مثل «جارٍ التحقق من المعلومات…» أو «جارٍ تنفيذ طلبك…» (وفي أدوات المتجر العمل نفسه، مثل «جارٍ البحث عن المنتجات…»). يمكنك كتابة نصك في حقل «النص المعروض أثناء الانتظار».

تُملأ الحقول الفرعية لحقول الكائن في الأداة في خانات منفصلة. وفي القائمة التي عناصرها كائنات اكتب أولًا متغير قائمة في «مصدر القائمة» (مثل قائمة إجراء أو نتيجة خطوة «تعديل قائمة»)، ثم اربط حقول العنصر في «حقول كل عنصر» بهذا الشكل: {item.sku}. يصبح كل عنصر من المصدر صفًا في القائمة، وإن تركت الربط فارغًا تُرسل العناصر كما هي.

لا تعمل الأداة التي تغيّر البيانات مرة أخرى عندما يضغط الزائر زر الرجوع أو يعيد إرسال رسالة. أما إذا مرّت المحادثة بهذه الخطوة من جديد (مثل العودة عبر قائمة) فتعمل مرة أخرى. والأداة التي تقرأ البيانات تُستدعى من جديد في كل مرة يصل فيها الزائر إلى الخطوة.

وإذا كان حقل إلزامي فارغًا أو لم تطابق قيمةٌ نوعَ حقلها لا تُستدعى الأداة وتنتقل الخطوة إلى «إذا فشل». ويعرض المحرر القيمة الثابتة التي لا تطابق نوعها تحذيرًا على الخطوة. تظهر الاستدعاءات في صفحة «الأدوات» › «إحصاءات الاستدعاءات».

إعادة المحاولة عند الفشل

إذا فعّلت «إعادة المحاولة عند الفشل» في خطوة إجراء التكامل أو استدعاء أداة تُشغَّل الخطوة مرة أخرى عند حدوث خطأ مؤقت. وعند نفاد المحاولات يتابع المسار من فرع «إذا فشل»؛ وإذا كان هذا الفرع فارغًا تُغلق المحادثة برسالة تفيد بحدوث مشكلة.

• «عدد المحاولات»: من 2 إلى 5، والافتراضي 3.
• «الانتظار بين المحاولات (ث)»: من 0 إلى 5 ثوانٍ، والافتراضي 1.

تستغرق كل المحاولات 18 ثانية كحد أقصى؛ وإذا نفد الوقت لا تُجرى المحاولات المتبقية.

لا يُعاد إلا عند الأخطاء المؤقتة: انتهاء المهلة، خطأ الاتصال، عطل لدى المزوّد وتجاوز حدّ الطلبات. أما في أخطاء مثل نقص الصلاحية أو حقل فارغ فتنتقل الخطوة مباشرة إلى «إذا فشل».

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