إعداد أدوات مخصصة للكابتن

اكتشف

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

الخطة وإمكانية الوصول: Business أو Enterprise (الأسعار والخطط). في خطة Startups، تعرض Tools عادةً عبارة Upgrade to use tools with Captain. لكل مساعد قائمة أدوات خاصة به. ينشئ المسؤولون الأدوات، ولا يمكن الاطلاع على بيانات الاعتماد المحفوظة إلا للمسؤولين. في الاستضافة الذاتية: يفعّل المسؤول الأعلى Custom Tools للحساب.

الإعداد والتجربة

قبل البدء

• نقطة نهاية HTTPS على اسم مضيف عام. يحظر Chatwoot بروتوكول HTTP العادي وعناوين IP وlocalhost والشبكات الخاصة وعناوين .local.

• يجب أن تقبل نقطة النهاية الاتصال خلال ثانيتين، وأن ترد خلال 20 ثانية، على ألا يتجاوز حجم الاستجابة 1 ميغابايت.

• بيانات اعتمادها، إن احتاجت إليها.

إنشاء أداة

1. انتقل إلى Captain > Tools وانقر Create a new tool. استخدم أولًا مبدّل المساعد في الأعلى لاختيار المساعد الذي ستُضاف إليه الأداة. ستُفتح الاستمارة في لوحة جانبية.

   

2. أدخل المعلومات التالية:

   • Tool Name: اسم مختصر، مثل "البحث عن طلب" (55 حرفًا أو أقل).

   • Description: متى ينبغي للمساعد استخدامها، بصياغة تشبه موجزًا لموظف جديد. يحدد هذا ما إذا كان المساعد سيختار الأداة.

   • Method: استخدم GET لقراءة البيانات؛ وPOST أو PUT أو PATCH لإرسال البيانات أو تغييرها؛ وDELETE لإزالة شيء ما.

   • Endpoint URL: استخدم {{ parameter_name }} للقيم التي يملؤها المساعد، مثل https://api.example.com/orders/``{{ order_id }}.

   • Authentication Type: None أو Bearer Token أو Basic Auth أو API Key (مع Header Name وHeader Value). استخدم هذا الخيار لبيانات الاعتماد.

   • Headers: انقر Add Header لإضافة ترويسات ثابتة تحتاج إليها واجهة API في كل استدعاء، مثل إصدار API أو معرّف المستأجر (حتى 16 ترويسة). تُرسَل القيم كما كُتبت تمامًا. يضبط Chatwoot بنفسه Authorization وHost وContent-Length وContent-Type وأي ترويسة يبدأ اسمها بـ X-Chatwoot، لذا لا يمكنك إضافة هذه الترويسات.

   • Parameters: انقر Add Parameter لكل قيمة ينبغي أن يحصل عليها المساعد من العميل. أدخل اسمًا ونوعًا ووصفًا، وحدد Required إذا لزم الأمر.

   • Add verified email: يضيف معلَمة. يضع Chatwoot في هذه المعلَمة البريد الإلكتروني الذي تحقّق منه العميل باستخدام رمز لمرة واحدة. في محادثات العملاء، لا يستطيع Captain رؤيته أو تغييره. استخدم هذه المعلَمة عندما تعثر واجهة API على العميل باستخدام البريد الإلكتروني، مثل https://api.example.com/orders?email={{ email }}. يمكن أن تحتوي الأداة على معلَمة بريد إلكتروني تم التحقق منه واحدة.

   • Require email verification: لا يستطيع Captain استخدام الأداة إلا بعد أن يتحقق العميل من بريده الإلكتروني باستخدام رمز لمرة واحدة. إذا كانت الأداة تتضمن معلَمة بريد إلكتروني تم التحقق منه، يكون هذا الإعداد مفعّلًا دائمًا.

   • Request Body Template (Optional): لاستخدامها مع POST أو PUT أو PATCH. يوجد هذا القالب وقالب الاستجابة ضمن Templates. قالب الطلب هو نص JSON. وهو يدعم Liquid، مثل {{ order_id }} للمعلَمة.

   • Response Template (Optional): استخرج الحقول التي يحتاج إليها المساعد، مثل Order {{ response.order_id }} status: {{ response.status }}. اقرأ رد واجهة API عبر response، مثل {{ response.status }}. اترك القالب فارغًا لإرسال JSON الخام إلى Captain.

     

   

3. انقر Test connection، ثم Create.

   

يعمل Test connection فقط مع نقاط النهاية التي لا تتضمن قوالب أو نص طلب. اختبر الحالات الأخرى في ساحة التجربة. تعني النتيجة الخضراء أن نقطة النهاية أعادت حالة 2xx: أي إنها متاحة وقبلت بيانات الاعتماد.

اختبرها

اطرح في Playground سؤالًا يحتاج إلى الأداة، مثل "أين طلبي رقم 1234؟". تحقق من أن الرد يستخدم بيانات حقيقية.

احمِ بيانات العملاء

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

عندما يستدعي Captain إحدى هذه الأدوات، يطلب من العميل عنوان بريده الإلكتروني. يرسل Chatwoot رمزًا من 6 أرقام إلى هذا البريد، ثم يكتبه العميل في المحادثة. لا تعمل الأداة إلا بعد أن يتحقق Chatwoot من صحة الرمز.

• ينطبق التحقق على محادثة واحدة فقط. وتستمر صلاحيته حتى ساعة واحدة، أو حتى 3 ساعات في محادثات البريد الإلكتروني. تبدأ المحادثة الجديدة دون تحقق.

• تنتهي صلاحية الرمز بعد 30 دقيقة. يمكن للعميل تجربة الرمز 5 مرات. ويرسل Chatwoot إلى العميل 5 رموز كحد أقصى خلال ساعة واحدة.

• لا يتحكم Require email verification في عنوان البريد الذي ترسل إليه الأداة. إذا حصلت واجهة API على البريد الإلكتروني من معلَمة عادية، فيمكن لـ Captain إرسال أي بريد إلكتروني. لجعل الأداة ترسل البريد الإلكتروني الذي تم التحقق منه فقط، استخدم Add verified email.

• يستطيع Chatwoot اكتشاف مؤشرات على أن الأداة تستخدم بيانات العملاء. إذا اكتشفها ولم يكن التحقق من البريد الإلكتروني مفعّلًا للأداة، فسيعرض Chatwoot Save without email verification? قبل حفظها. انقر Go back أو Save anyway.

• في ساحة التجربة واقتراحات الردود، يكون المستخدم أحد أعضاء الفريق. يملأ Captain معلَمة البريد الإلكتروني الذي تم التحقق منه. وتُظهر لك النتيجة ما إذا كان Chatwoot قد تحقق من ذلك البريد الإلكتروني.

• في مجموعات الأدوات المثبّتة، يستطيع المسؤولون تفعيل Require email verification أو إيقافه.

الاستفادة القصوى

• تعمل الأدوات المخصصة على أفضل وجه مع عمليات البحث ذات المدخلات الواضحة، مثل حالة طلب أو حجز أو سجل بحسب المعرّف.

• يمكن أن يتضمن كل مساعد ما يصل إلى 50 أداة. مع ذلك، اجعل القائمة قصيرة: فكلما زاد عدد الأدوات، زاد احتمال اختيار المساعد للأداة الخاطئة.

• تؤثر إضافة أداة أو تحريرها أو إيقافها أو حذفها في المساعد الذي تعرضه فقط. نُسخت الأدوات التي كانت موجودة قبل أن تصبح الأدوات خاصة بكل مساعد إلى جميع المساعدين، لذا تحقق من كل مساعد.

• هل تستخدم عدة مساعدين؟ خصص لكل واحد الأدوات التي يحتاج إليها فقط.

• أوقف الأداة باستخدام مفتاح التبديل بدلًا من حذفها. إذا كان هناك سيناريو يستخدمها، فسينبهك Chatwoot أولًا. راجع إعداد ضوابط Captain وإرشاداته وسيناريوهاته.

• يرسل Chatwoot ترويسات مع كل طلب. وتُعرّف هذه الترويسات نظامك بالحساب والمحادثة وجهة الاتصال والمساعد وصندوق الوارد.

  • تحتوي X-Chatwoot-Verified-Email على البريد الإلكتروني الذي تحقّق منه العميل باستخدام رمز لمرة واحدة. إذا لم يتحقق العميل، فلن يرسل Chatwoot هذه الترويسة.

  • تحتوي X-Chatwoot-Contact-Email على البريد الإلكتروني المسجل في سجل جهة الاتصال. يمكن لأي شخص إدخال هذا البريد الإلكتروني. لا تستخدمه لإرجاع بيانات خاصة.

  • تكون قيمة X-Chatwoot-Contact-Inbox-Verified هي true عندما يتحقق التحقق من الهوية (HMAC) من جهة الاتصال. لا تتحقق هذه الترويسة من البريد الإلكتروني.

  إذا أعاد نظامك بيانات خاصة، فتحقق من X-Chatwoot-Verified-Email، أو فعّل التحقق من البريد الإلكتروني للأداة. راجع كيفية تفعيل التحقق من الهوية في Chatwoot؟.

• إذا أعادت واجهة API نصًا كتبه العملاء، فأعِد الحقول المنظّمة التي تحتاج إليها فقط. يقرأ Captain الرد كما هو، لذا قد يتضمن النص الحر تعليمات قد يتبعها.

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

لمعرفة أسباب أخرى: استكشاف أخطاء Captain وإصلاحها.