كيفية إعداد أدوات مخصصة لـ Captain؟
تتيح "الأدوات المخصصة" لـ Captain الاتصال بواجهات برمجة التطبيقات (API) الخارجية الخاصة بك أثناء المحادثات — بحيث يمكنه
التحقق من حالة الضمان، أو التحقق من تغطية الخدمة، أو استرداد البيانات من خدماتك الخاصة دون الحاجة إلى تحويل المكالمة
إلى موظف خدمة عملاء.
عندما يطرح العميل سؤالاً، يستخرج Captain القيم ذات الصلة من المحادثة، ويدرجها في طلب واجهة برمجة التطبيقات (API) الخاص
بك، ويستخدم الرد لتكوين إجابته.
تتوفر الأدوات المخصصة في خطة Business وما فوقها.
إنشاء أداة
انتقل إلى Captain -> Tools وانقر على Create a new tool.
املأ الحقول التالية:
اسم الأداة — اسم قصير مثل "البحث عن الضمان" أو "التحقق من منطقة الخدمة" (بحد أقصى 55 حرفًا).
الوصف — أخبر Captain متى يستخدم هذه الأداة. هذا هو الحقل الأكثر أهمية. اكتب الوصف كما لو كنت تطلع موظف الدعم على
الموضوع: "يتحقق من حالة ضمان المنتج من خلال رقمه التسلسلي." ستؤدي الأوصاف الغامضة مثل "Warranty API" إلى فقدان
Captain لفرص استخدام الأداة.
الطريقة — اختر GET (لاسترداد البيانات) أو POST (لإرسال البيانات).
عنوان URL لنقطة النهاية — عنوان URL لواجهة برمجة التطبيقات (API) الخاصة بك. استخدم {{ parameter_name }} لإدراج القيم
المستخرجة من المحادثة:
https://api.yourcompany.com/v1/warranty/{{ serial_number }}
يجب أن يستخدم عنوان URL بروتوكول HTTPS، ويجب أن يكون اسم مضيف (وليس عنوان IP)، ولا يمكن أن يشير إلى localhost أو شبكات
خاصة.
المصادقة — اختر كيفية مصادقة واجهة برمجة التطبيقات (API) لطلباتك:
- لا شيء — لا توجد مصادقة
- رمز حامل — يرسل الرمز الخاص بك في رأس Authorization
- المصادقة الأساسية — يرسل اسم المستخدم وكلمة المرور
- مفتاح واجهة برمجة التطبيقات — يرسل اسم رأس وقيمة مخصصين (على سبيل المثال، X-API-Key)
بيانات اعتماد المصادقة مرئية فقط لمسؤولي الحساب.
المعلمات — حدد ما يجب على Captain استخراجه من رسالة العميل. تحتاج كل معلمة إلى اسم ونوع ووصف. على سبيل المثال:
serial_number (سلسلة) — "رقم تسلسل المنتج، الموجود على ظهر الجهاز."
قالب الطلب (POST فقط) — قالب نص JSON يستخدم صيغة Liquid.
قالب الاستجابة — يتحكم في ما يراه Captain من استجابة واجهة برمجة التطبيقات (API) الخاصة بك. إذا تُرك فارغًا، يتلقى
Captain JSON الخام.
استخدم Liquid لاستخراج الحقول ذات الصلة، على سبيل المثال: Serial {{ response.serial_number }}: {{
response.warranty_status }}. Expires: {{ response.expiry_date }}.
استخدم response للوصول إلى نص JSON الذي تم تحليله. تساعد قوالب الاستجابة Captain على التركيز على البيانات ذات الصلة
وتجنب الحقول الداخلية مثل معرفات قاعدة البيانات أو معلومات التصحيح.
اختبار أداتك
انقر على اختبار الاتصال قبل الحفظ للتحقق من إمكانية الوصول إلى نقطة النهاية الخاصة بك. يبلغ الاختبار عن رمز حالة HTTP.
تعني النتيجة الخضراء (HTTP 200–299) أن الاتصال والمصادقة يعملان. لاحظ أن الاختبار يرسل عنوان URL دون ملء قيم المعلمات،
لذا فهو يتحقق فقط من إمكانية الوصول إلى نقطة النهاية الخاصة بك وقبول بيانات اعتمادك.
إذا فشل الاختبار، تحقق مما يلي:
- 401 غير مصرح به — بيانات اعتمادك غير صحيحة. تحقق جيدًا من رمز الحامل (bearer token) أو مفتاح واجهة برمجة التطبيقات
(API key) أو اسم المستخدم/كلمة المرور.
- 403 ممنوع — ترفض واجهة برمجة التطبيقات (API) الطلب. إذا كنت تحتاج إلى التحقق من الهوية، فلاحظ أن الطلبات التجريبية
لا تتضمن رؤوس الاتصال.
- 404 غير موجود — عنوان URL لنقطة النهاية غير صحيح. تحقق من المسار وتأكد من أن واجهة برمجة التطبيقات (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 ثانية
متى تستخدم الأدوات المخصصة
تعد الأدوات المخصصة هي الأنسب لعمليات البحث المنظمة ذات المدخلات التي يمكن التنبؤ بها — مثل التحقق من حالة النظام، أو
استرداد الجداول الزمنية، أو البحث عن السجلات حسب المعرف. إذا كان لديك بالفعل تكامل Voxys Connect مخصص لحالة الاستخدام
الخاصة بك (على سبيل المثال، Shopify للتجارة الإلكترونية)، فاستخدمه بدلاً من ذلك — حيث تتعامل عمليات التكامل المخصصة مع
البحث والمطابقة التقريبية ومزامنة البيانات بشكل أكثر موثوقية من استدعاء API واحد.
أمثلة
البحث عن الضمان
عندما يسأل العميل عما إذا كان منتجه لا يزال تحت الضمان، يمكن لـ Captain التحقق من ذلك باستخدام الرقم التسلسلي.
- اسم الأداة: البحث عن الضمان
- الوصف: يتحقق من حالة ضمان المنتج من خلال رقمه التسلسلي. استخدم هذه الأداة عندما يسأل العميل عما إذا كان منتجه
مشمولًا بالضمان، أو متى تنتهي صلاحية الضمان، أو ما نوع التغطية التي يتمتع بها.
التحقق من منطقة الخدمة
بالنسبة للشركات التي تعمل في مناطق محددة — يسأل العملاء عما إذا كانت الخدمة متوفرة في موقعهم.
- اسم الأداة: التحقق من منطقة الخدمة
- الوصف: يتحقق مما إذا كانت الخدمة أو التوصيل متاحين في منطقة معينة باستخدام الرمز البريدي للعميل أو اسم المدينة.
تعمل الأدوات المخصصة بشكل أفضل عندما تكون المدخلات مباشرة واستجابة واجهة برمجة التطبيقات (API) متوقعة — وتعد عمليات
التحقق من الحالة والبحث والاستعلامات المنظمة الأخرى مناسبة تمامًا.