متى تستخدم واجهة REST API في AI SNS CHAT، وكيف تبني تكاملاً آمناً يحترم حدود المعدل ويدعم البث وإشعارات Webhook الموقّعة.
تمتلك شركتك نظام طلبات أو برنامج حجوزات أو واجهة تطبيق خاصة، وتريد أن يتحدث وكيل الذكاء الاصطناعي معها مباشرة. هنا يأتي دور الواجهة البرمجية، لكن استخدامها دون تخطيط قد يكلّفك وقتاً في بناء ما هو جاهز أصلاً. في هذا المقال نوضح متى تحتاج REST API فعلاً، وما عناصرها الأساسية، وكيف تصمم تكاملاً متيناً وتطلقه بأمان.
متى تكون الواجهة البرمجية هي الأداة الصحيحة، ومتى لا تكون؟
القاعدة البسيطة: لا تكتب شيفرة لأمر توفره المنصة جاهزاً. إذا كان هدفك نشر وكيل على واتساب أو إنستغرام أو دردشة الموقع، فهذه قنوات مدمجة تُفعَّل من لوحة التحكم دون سطر برمجي واحد. أما الواجهة البرمجية فمكانها حين تحتاج شيئاً لا تغطيه القنوات الجاهزة.
تناسبك الواجهة البرمجية في حالات مثل:
- بناء واجهة محادثة خاصة داخل تطبيقك أو بوابة عملائك، بتصميمك ومفردات علامتك التجارية.
- ربط الوكيل بنظام داخلي لا يملك موصلاً جاهزاً، مثل نظام فوترة محلي أو ERP مخصص.
- استقبال أحداث من المنصة في خدماتك الخاصة، كتسليم محادثة لموظف أو تسجيل عميل محتمل.
- أتمتة عمليات متكررة على مستوى المساحة، بدلاً من النقر اليدوي في اللوحة.
ولا تحتاجها في الحالات التالية:
- نشر وكيل على واتساب أو Messenger أو إنستغرام: تكفي القنوات المدمجة.
- قراءة بيانات من أدوات شائعة مثل HubSpot أو Google Sheets أو WooCommerce: توجد أدوات بحث مدمجة للقراءة فقط.
- إرسال تنبيهات تسليم المحادثة إلى Slack أو Teams أو البريد: هذه مدعومة جاهزاً.
اللبنات الأساسية
تقوم الواجهة على ثلاثة عناصر تكفي لمعظم التكاملات.
مفاتيح API
تُنشأ المفاتيح من إعدادات مساحة العمل ثم مفاتيح API. يظهر المفتاح مرة واحدة فقط عند إنشائه، لذا احفظه فوراً في مدير أسرار آمن. ويمكنك إلغاء أي مفتاح في أي وقت إذا شككت في تسرّبه. هذه الميزة متاحة بدءاً من خطة Hobby.
طلبات JSON وبث الردود
الواجهة من نوع REST وتتبادل البيانات بصيغة JSON. وإذا أردت أن تظهر الإجابة في واجهتك كلمة بكلمة كما يحدث في تطبيقات المحادثة الحديثة، فهي تدعم البث عبر SSE بتمرير المعامل stream=1. هذا يحسّن إحساس المستخدم بالسرعة، خصوصاً مع الإجابات الطويلة.
إشعارات Webhook الموقّعة
بدلاً من أن يسأل خادمك المنصة باستمرار هل حدث شيء جديد، تُرسل المنصة الحدث إليك. وتُوقَّع هذه الإشعارات بآلية HMAC، ويتوفر سجل تسليم يتيح لك مراجعة ما أُرسل وما نجح وما فشل. التوقيع هو ما يثبت لخادمك أن الطلب جاء من AI SNS CHAT لا من طرف منتحل.
- 01تطبيقك أو خادمك
- 02طلب JSON بمفتاح API
- 03وكيل AI SNS CHAT
- 04رد مباشر أو بث SSE وإشعار Webhook موقّع
احترم حدود المعدل المنشورة
تنشر المنصة حدوداً واضحة في مرجع الواجهة، وتصميمك يجب أن يبنى عليها منذ اليوم الأول لا بعد أول عطل:
| نوع الطلب | الحد المنشور |
|---|---|
| المصادقة | 20 طلباً كل 5 دقائق لكل عنوان IP |
| الدردشة العامة | 30 طلباً في الدقيقة لكل عنوان IP |
| الاستعلام الدوري (poll) | 120 طلباً في الدقيقة |
لنفترض مثالاً توضيحياً: متجر إلكتروني يضع أداة المحادثة في تطبيقه، وتخرج حملة إعلانية في رمضان فيدخل مئات الزوار في الوقت نفسه من شبكة مكتب أو من مزوّد إنترنت يشارك عنوان IP واحداً بين كثيرين. قد تصطدم عندها بحد الدردشة العامة لكل IP. لذلك لا تعتمد على أن الحركة ستكون موزعة دائماً.
ما يساعدك عملياً:
- لا تطلب المصادقة في كل رسالة. احتفظ بالجلسة واستخدمها طوال المحادثة.
- فضّل Webhook على الاستعلام الدوري كلما أمكن، فهو يوفر عليك آلاف الطلبات الفارغة.
- تعامل مع رفض الطلب بهدوء. أعد المحاولة بعد مهلة متزايدة، وأظهر للمستخدم رسالة لطيفة بدل خطأ تقني.
- راقب نفسك. سجّل عدد الطلبات المرفوضة في لوحة المراقبة لديك لتعرف متى تقترب من الحد.
أنماط تصميم تنجح في الواقع
نمط الوسيط الخلفي
لا تضع مفتاح API في تطبيق الجوال أو في شيفرة المتصفح مهما كانت الأسباب. أنشئ خدمة وسيطة صغيرة على خادمك، تتحدث إليها واجهتك، وهي وحدها تحمل المفتاح وتتصل بالمنصة. بهذا تتحكم في ما يمرّ، وتستطيع إضافة التحقق من هوية المستخدم قبل أي طلب.
نمط الحدث ثم الإجراء
عندما يصل Webhook يعلن تسليم محادثة إلى موظف، أنشئ تذكرة في نظامك الداخلي وأرسل تنبيهاً إلى الفريق. اجعل المعالج سريعاً: أكّد الاستلام أولاً ثم نفّذ العمل الثقيل في الخلفية، حتى لا تتراكم المحاولات.
نمط التكرار الآمن
قد يصل الإشعار نفسه أكثر من مرة في أي نظام موزع. خزّن معرّف الحدث، وتجاهل ما عالجته سابقاً، لتتجنب إنشاء تذكرتين أو إرسال رسالة مكررة للعميل.
نمط الرجوع إلى الإنسان
صمّم واجهتك بحيث تعرض للعميل حالة واضحة حين يتدخل موظف. ففي الأعمال الخليجية يتوقع العميل غالباً أن يرد عليه إنسان في الشؤون الحساسة كالمبالغ والاسترجاع، وتجربة تعطي شعوراً بالانتقال السلس تبني الثقة.
قائمة تحقق أمنية قبل الإطلاق
راجع هذه النقاط قبل أن يلمس تكاملك بيانات عملاء حقيقيين:
- المفاتيح: مخزنة في مدير أسرار، لا في المستودع ولا في تطبيق العميل. وتذكّر أنها لا تُعرض إلا مرة واحدة.
- الإلغاء: جرّب إلغاء مفتاح وإنشاء بديل قبل الإطلاق، حتى يكون الإجراء مألوفاً لفريقك في الطوارئ.
- توقيع Webhook: تحقق من توقيع HMAC في كل طلب وارد، وارفض أي طلب لا يطابق. لا تعتمد على سرّية عنوان الاستقبال وحده.
- HTTPS فقط لنقاط الاستقبال، مع حصر الأذونات الممنوحة لحساب الخدمة.
- الحد الأدنى من البيانات: لا ترسل إلى الوكيل إلا ما يحتاجه للإجابة. أرقام الهوية والبطاقات لا مكان لها في الرسائل.
- سجلات نظيفة: لا تطبع المفاتيح أو الأسرار في سجلات تطبيقك.
- المراجعة: يسجل سجل النشاط في إعدادات مساحة العمل من أنشأ أو عدّل أو حذف، فاستخدمه لمعرفة من غيّر ماذا بعد الإطلاق.
الاختبار والإطلاق التدريجي
لا تبدأ على بيئة العملاء. اتبع هذا التسلسل:
- جرّب في Playground سلوك الوكيل ورده على الأسئلة الصعبة قبل ربطه بأي نظام، فتفصل مشكلات الوكيل عن مشكلات التكامل.
- أنشئ وكيلاً تجريبياً منفصلاً عن الوكيل الحي، واربط تكاملك به أولاً. يمكنك نسخ الوكيل الحالي بميزة Duplicate لتحصل على الشخصية والبيانات نفسها دون المحادثات.
- اختبر الأعطال عمداً: مفتاح ملغى، توقيع خاطئ، خادم متوقف، رد بطيء. شاهد كيف تتصرف واجهتك.
- راجع سجل تسليم Webhook لتتأكد أن الأحداث تصل وتُعالج.
- أطلق على شريحة صغيرة من المستخدمين أو صفحة واحدة، ثم وسّع تدريجياً.
- أبقِ نقطة استرجاع: تتيح المنصة نقاط استعادة للوكيل (حتى 40 لكل وكيل)، فإذا تغيّر سلوكه بعد تعديل يمكنك الرجوع إلى حالة سابقة.
مثال توضيحي: شركة عقارية تفتح واجهة المحادثة الجديدة لأول عشرين بالمئة فقط من زوار صفحة المشاريع، ثم تقارن جودة المحادثات في سجلات الدردشة قبل تعميمها على الموقع كله.
كيف تنفّذ هذا في AI SNS CHAT
إليك المسار العملي خطوة بخطوة داخل المنصة.
1. تأكد من الخطة. مفاتيح API والتكاملات متاحة من خطة Hobby فما فوق. أما الخطة المجانية فتناسب التجربة والتعرف على الوكيل. الأسعار تُقرأ من صفحة الأسعار وقت العرض، وقد تتغير.
2. أنشئ المفتاح. من إعدادات مساحة العمل افتح مفاتيح API وأنشئ مفتاحاً جديداً، وانسخه فوراً لأنه لا يُعرض ثانية. سمِّ كل مفتاح باسم النظام الذي يستخدمه، ليسهل إلغاء الصحيح عند الحاجة.
3. اقرأ مرجع الواجهة. يحدد المرجع المنشور الطلبات المتاحة وحدود المعدل وتفاصيل التوقيع. اعتمد عليه لا على التخمين.
4. فعّل الاستقبال. إذا أردت إشعارات Webhook، فعّلها واختبرها، ثم راقب سجل التسليم لتتأكد من وصولها. تحقق من توقيع HMAC عند خادمك.
5. استفد مما هو جاهز. قبل أن تكتب شيفرة، افتح قسم القنوات من الشريط الجانبي. تجد هناك واتساب وMessenger وإنستغرام وأداة الدردشة وصفحة المساعدة وغيرها، وتجد قناة API نفسها ضمن القائمة. راجع أيضاً صفحة الاتصالات لمعرفة ما هو مبني وما هو قيد الإعداد. ومن قسم الإجراءات يمكنك إضافة إجراء مخصص إذا كان المطلوب استدعاء خدمة خارجية من داخل المحادثة (عدد الإجراءات لكل وكيل يختلف حسب الخطة).
6. اربط الفريق. تنبيهات تسليم المحادثة يمكن أن تصل إلى Slack أو Teams أو LINE WORKS أو واتساب أو البريد أو Webhook، وتُوزَّع الحالات تلقائياً على من هو في المناوبة من قسم الجدولة في Helpdesk (يتطلب Standard أو أعلى).
7. استخدم Synthia مدير الأسطول الذكي، إذا ضللت الطريق داخل اللوحة. تستطيع أن تسألها بالصوت أو بالنص، وتنقلك إلى الشاشة المطلوبة وتبرز لك العنصر الذي تبحث عنه.
8. استخدم نطاقك الخاص. إذا أردت أن يظهر سكربت التضمين ورابط الوكيل باسم نطاقك الفرعي، فمن إعدادات الوكيل ثم النطاقات المخصصة يمكنك ربط CNAME، وهو متاح من Hobby فما فوق.
بهذا الترتيب تحصل على تكامل يضيف إلى المنصة ما ينقصك فقط، ويترك لها ما تقوم به أصلاً. وللتفاصيل الكاملة للميزات راجع صفحة الميزات، وللبدء راجع التسجيل.
الأسئلة الشائعة
ما الخطة المطلوبة لاستخدام REST API؟
مفاتيح API متاحة من خطة Hobby فما فوق. الخطة المجانية لا تشمل المفاتيح، لكنها تكفي لتجربة الوكيل في Playground. تُعرض الأسعار الحالية في صفحة /pricing لأنها تُقرأ وقت العرض وقد يعدّلها المسؤول.
هل أستطيع بث الردود إلى واجهتي الخاصة؟
نعم. تدعم الواجهة البث عبر SSE بتمرير المعامل stream=1، فتعرض الإجابة تدريجياً أثناء توليدها بدل انتظار اكتمالها. ننصح بتمرير البث عبر خدمتك الوسيطة حتى يبقى مفتاح API بعيداً عن المتصفح.
كيف أتأكد أن Webhook قادم فعلاً من AI SNS CHAT؟
إشعارات Webhook موقّعة بآلية HMAC. احسب التوقيع عند خادمك وفق ما يوضحه مرجع الواجهة وقارنه بالتوقيع الوارد، وارفض أي طلب لا يطابق. ويتيح سجل التسليم مراجعة ما أُرسل ونتيجته.
ما حدود المعدل؟
المنشور حالياً: المصادقة 20 طلباً كل 5 دقائق لكل IP، والدردشة العامة 30 طلباً في الدقيقة لكل IP، والاستعلام الدوري 120 طلباً في الدقيقة. صمّم تكاملك على إعادة المحاولة بمهلة متزايدة وفضّل Webhook على الاستعلام المتكرر.
هل أحتاج الواجهة لوضع وكيل على واتساب أو Messenger؟
لا. واتساب وMessenger وإنستغرام قنوات مدمجة تُفعَّل من قسم القنوات في اللوحة دون برمجة. الواجهة البرمجية للحالات الخاصة فقط، كواجهة محادثة داخل تطبيقك أو ربط نظام داخلي.


