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

تتيح الأدوات المخصصة لـ Captain إمكانية استدعاء واجهات برمجة التطبيقات الخارجية الخاصة بك أثناء المحادثات — بحيث يمكنه التحقق من حالة الضمان، أو التحقق من تغطية الخدمة، أو جلب بيانات من خدماتك الخاصة دون الحاجة إلى تحويل المحادثة إلى وكيل بشري.

عندما يطرح العميل سؤالاً، يستخرج Captain القيم ذات الصلة من المحادثة، ويُدرجها في طلب الـ API الخاص بك، ويستخدم الاستجابة لتكوين رده.

الأدوات المخصصة متوفرة في خطة الأعمال وما فوق.

إنشاء أداة

انتقل إلى Captain -> الأدوات ثم انقر على إنشاء أداة جديدة.

املأ الحقول التالية:

اسم الأداة — اسم قصير مثل "التحقق من الضمان" أو "تحقق من منطقة الخدمة" (بحد أقصى 55 حرفًا).

الوصف — أبلغ Captain متى يجب استخدام هذه الأداة. هذا هو أهم حقل. اكتبه كما لو كنت تشرح لوكيل دعم: "يتحقق من حالة ضمان منتج باستخدام الرقم التسلسلي." الأوصاف غير الواضحة مثل "واجهة ضمان" ستؤدي إلى تفويت Captain لفرص استخدام الأداة.

طريقة الطلب — اختر GET (لجلب البيانات) أو POST (لإرسال البيانات).

رابط النهاية الطرفية — عنوان الـ API الخاص بك. استخدم {{ parameter_name }} لإدراج القيم المستخرجة من المحادثة:

https://api.yourcompany.com/v1/warranty/{{ serial_number }}

يجب أن يستخدم الرابط HTTPS، ويجب أن يكون اسم مضيف (وليس عنوان IP)، ولا يمكن أن يشير إلى localhost أو الشبكات الخاصة.

المصادقة — اختر طريقة مصادقة API الخاصة بك:

• بدون — بدون مصادقة

• Token Bearer — يرسل الرمز الخاص بك في ترويسة Authorization

• مصادقة أساسية — يرسل اسم مستخدم وكلمة مرور

• مفتاح API — يرسل اسم ترويسة وقيمة مخصصة (مثال، X-API-Key)

بيانات اعتماد المصادقة تكون مرئية فقط لمسؤولي الحساب.

المعلمات — عرّف ما يجب على Captain استخراجه من رسالة العميل. كل معلمة تحتاج إلى اسم، نوع، ووصف. على سبيل المثال: serial_number (سلسلة نصية) — "الرقم التسلسلي للمنتج، يوجد في ظهر الجهاز."

قالب الطلب (POST فقط) — قالب JSON باستخدام لغة Liquid.

قالب الاستجابة — يتحكم بما يراه Captain من استجابة الـ API الخاصة بك. إذا تُرك فارغًا، يتلقى Captain JSON الخام.

استخدم Liquid لاستخراج الحقول ذات الصلة، على سبيل المثال: الرقم التسلسلي {{ response.serial_number }}: {{ response.warranty_status }}. ينتهي في: {{ response.expiry_date }}.

استخدم response للوصول إلى جسم JSON الذي تم تحليله. تساعد قوالب الاستجابة Captain على التركيز على البيانات ذات الصلة وتجنب الحقول الداخلية مثل معرفات قواعد البيانات أو معلومات تصحيح الأخطاء.

اختبار أداتك

انقر على اختبار الاتصال قبل الحفظ للتحقق من أن النهاية الطرفية الخاصة بك قابلة للوصول. يقدم الاختبار رمز حالة HTTP.

تعني النتيجة الخضراء (HTTP 200–299) أن الاتصال والمصادقة يعملان. لاحظ أن الاختبار يرسل الرابط بدون تعبئة قيم المعلمات، لذا فهو يتحقق فقط من أن النهاية الطرفية الخاصة بك متاحة وأن بيانات الاعتماد الخاصة بك مقبولة.

إذا فشل الاختبار، تحقق من التالي:

• 401 غير مصرح — بيانات الاعتماد الخاصة بالمصادقة غير صحيحة. تحقق مجددًا من رمز bearer، مفتاح API، أو اسم المستخدم/كلمة المرور.

• 403 محظور — الـ API الخاص بك يرفض الطلب. إذا كنت تطلب التحقق من الهوية، لاحظ أن الطلبات التجريبية لا تتضمن ترويسات الاتصال.

• 404 غير موجود — رابط النهاية الطرفية غير صحيح. تحقق من المسار وتأكد من أن API يعمل.

• انتهت المهلة — أخذ الـ API الخاص بك وقتًا طويلاً للرد. الأدوات المخصصة لديها مهلة 30 ثانية؛ تأكد من أن النهاية الطرفية تستجيب خلال تلك المهلة.

السياق المُرسل مع كل مكالمة أداة

عندما يستدعي Captain الـ API خاصتك، فإنه يتضمن ترويسات بيانات وصفية حتى يعرف النظام الخلفي لديك السياق:

• X-Chatwoot-Account-Id — معرف حسابك

• X-Chatwoot-Conversation-Id — معرف المحادثة

• X-Chatwoot-Contact-Email — البريد الإلكتروني للعميل (إن وُجد)

• X-Chatwoot-Contact-Inbox-Verified — ما إذا كانت هوية العميل تم التحقق منها عبر HMAC

• X-Chatwoot-Assistant-Id — معرف المساعد Captain الذي يجري الاتصال

• X-Chatwoot-Tool-Slug — معرف الأداة الداخلي

• X-Chatwoot-Contact-Id — معرف جهة اتصال العميل

• X-Chatwoot-Contact-Phone — رقم هاتف العميل (إن وُجد)

• X-Chatwoot-Conversation-Display-Id — رقم عرض المحادثة

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

الأمان

الحمايات المدمجة:

• جميع النهايات الطرفية يجب أن تستخدم HTTPS

• الطلبات إلى نطاقات IP الخاصة، وlocalhost، ونطاقات .local محظورة

• لا يتم تتبع عمليات إعادة التوجيه HTTP

• الحد الأقصى لحجم الاستجابة 1 ميغابايت

• بيانات الاعتماد مرئية فقط للمسؤولين

التحقق من الهوية: إذا كانت أداتك تُرجع بيانات خاصة بالعميل (طلبات، فواتير، تفاصيل الحساب)، يجب على API الخاص بك التحقق من ترويسة X-Chatwoot-Contact-Inbox-Verified. بدون تفعيل التحقق من HMAC على صندوق بريدك، يمكن لأي زائر إدخال أي عنوان بريد إلكتروني في أداة الدردشة. لا تُرجع بيانات حساسة إلا إذا كانت هذه الترويسة true. للأدوات التي تُرجع بيانات عامة، لا داعي لهذا التحقق.

حقن الأوامر: إذا كان API الخاص بك يُرجع محتوى يُنشئه المستخدم (مراجعات، منشورات المنتدى)، فقد يؤثر نص خبيث على سلوك Captain. استخدم قوالب الاستجابة لاستخراج الحقول المهيكلة فقط، ونظِّف المحتوى على جانب الـ API الخاص بك.

الحدود

• الحد الأقصى للأدوات لكل حساب — 15

• الموصى به — 10 أو أقل. تظهر رسالة تحذير عند أكثر من 10؛ قد يصعب على Captain اختيار الأداة المناسبة إذا زاد العدد.

• طول اسم الأداة — 55 حرفًا

• حجم الاستجابة — حتى 1 ميغابايت

• مهلة الطلب — 30 ثانية

متى تستخدم الأدوات المخصصة

الأدوات المخصصة هي الأنسب للاستعلامات المهيكلة ذات المدخلات المتوقعة — مثل التحقق من حالة النظام، جلب الجداول الزمنية، أو البحث في السجلات بواسطة معرف. إذا كان لديك بالفعل تكامل Chatwoot مخصص لحالتك (مثل Shopify للتجارة الإلكترونية)، فالأفضل استخدامه — التكاملات المخصصة تدير البحث، والمطابقة الغامضة، ومزامنة البيانات بكفاءة أعلى من مجرد استدعاء API واحد.

أمثلة

التحقق من الضمان

عندما يسأل العميل عما إذا كان منتجه لا يزال تحت الضمان، يمكن لـ Captain التحقق باستخدام الرقم التسلسلي.

• اسم الأداة: التحقق من الضمان

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

التحقق من منطقة الخدمة

للشركات التي تعمل في مناطق معينة — يسأل العملاء عما إذا كانت الخدمة متوفرة في موقعهم.

• اسم الأداة: التحقق من منطقة الخدمة

• الوصف: يتحقق مما إذا كانت الخدمة أو التوصيل متوفرة في منطقة معينة باستخدام الرمز البريدي للعميل أو اسم المدينة.

تعمل الأدوات المخصصة بأفضل صورة عندما تكون المدخلات واضحة واستجابة الـ API متوقعة — التحقق من الحالة، والبحث، والاستعلامات المهيكلة الأخرى هي حالات استخدام ممتازة.