وثائق Make Agent Fast

نظرة عامة على الموصّلات

وجّه وكيلًا واحدًا إلى Telegram وWhatsApp وMessenger وInstagram وDiscord وKakaoTalk باستخدام بيانات اعتماد يمكن التحقق منها.

نظرة سريعة

وجّه وكيلًا واحدًا إلى Telegram وWhatsApp وMessenger وInstagram وDiscord وKakaoTalk باستخدام بيانات اعتماد يمكن التحقق منها.

توجيه الموصّلاتوكيل واحد وقنوات متعددة ومعرفة وصندوق وارد مشتركان

Telegram WhatsApp Messenger Instagram Discord KakaoTalk

تستقبل الموصّلات الأحداث من منصة مراسلة خارجية، وتعالج النص أو الصوت المدعوم وتحوّله إلى صيغة موحّدة، وتشغّل وكيل الموقع نفسه، ثم تعيد ردًا مناسبًا للقناة. يحصل كل مستخدم خارجي على سجل محادثات خاص بالقناة يظهر في المحادثات.

يتطلب ربط قناة جديدة الاشتراك في باقة Operate أو Scale. تستمر الاتصالات الحالية في العمل على باقة Launch.

درس مرئي · الحلقة 9Messenger وDiscord وKakaoTalk0:15 – 4:09 · صوت بالإنجليزيةالحلقة كاملة والفصول →

مصفوفة الإمكانات#

القناة	النص الوارد	الصوت الوارد	النص الصادر	الصوت الصادر	إعداد المزوّد بعد الحفظ
Telegram	نعم	نعم	نعم	اختياري	يُسجَّل الـ webhook تلقائيًا
WhatsApp	نعم	نعم	نعم	اختياري	أضف webhook من Meta واشتراك `messages`
Messenger	نعم	نعم	نعم	لا	أضف webhook من Meta واشترك في الصفحة
Instagram	نعم	نعم	نعم	لا	أضف webhook الخاص بـ Instagram من Meta واشترك في `messages`
Discord	سؤال عبر `/ask`	لا	رد عبر `/ask`	لا	الصق نقطة نهاية التفاعلات؛ يتم تسجيل الأمر تلقائيًا
KakaoTalk	نعم	لا	رد مضمّن عبر المهارة	لا	أضف عنوان URL الخاص بالمهارة والترويسة والكتلة في Open Builder

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

قبل الربط#

اختبر الوكيل المقصود في لوحة التحكم. يمكن لموصّل في حالة المسودة أن يرد أيضًا.
لا تحتاج إلى مفتاح نموذج: توفّر المنصة النماذج. مفاتيح المزوّد اختيارية ومتاحة في باقة Scale فقط؛ راجع مفاتيح المزوّد.
أنشئ تطبيقًا أو بوتًا أو رقمًا أو قناة مخصصة في المزوّد الخارجي. لا تعِد استخدام بيانات اعتماد تخص تكاملًا إنتاجيًا غير مرتبط.
تأكد من أن بيئة النشر لديك تحتوي على عنوان أساسي عام للموصّل عبر HTTPS. لا تستطيع webhooks الخاصة بالمزوّدين التسليم إلى localhost دون نفق تطوير آمن.
افتح صفحة القنوات الخاصة بالوكيل واختر القناة.

عند الحفظ، يتصل Make Agent Fast بالمزوّد للتحقق من بيانات الاعتماد المُرسَلة. تعني تسمية «متصل» أن التحقق من بيانات الاعتماد وأي تجهيز تلقائي قد اكتملا؛ ولا تثبت أن خطوة يدوية في وحدة تحكم Meta أو Discord أو Kakao قد أُنجزت.

التعامل مع بيانات الاعتماد#

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

رمز بوت Telegram
رموز الوصول وسر التطبيق في Meta
رمز بوت Discord
مفتاح REST API وسر البوت في Kakao

لا تضعها في JavaScript داخل المتصفح، ولا في لقطات الشاشة، ولا في تذاكر الدعم، ولا في نظام التحكم بالإصدارات. عنوان webhook URL ورمز التحقق (verify token) من Meta هما قيم إعداد مخصّصة للنسخ إلى وحدة تحكم المزوّد المطابقة؛ ولا تحل محل بيانات اعتماد المزوّد.

الربط عبر API#

استخدم مفتاح MAF API محفوظًا على الخادم مع النطاق connectors:write. الكائن credentials الخاص بكل قناة للكتابة فقط. تحذف الاستجابة الأسرار بنصها الصريح وتتضمن عنوان webhook URL المطلوب للإعداد اليدوي لدى المزوّد.

curl -X POST "https://makeagent.fast/api/v1/sites/$SITE_ID/connectors" \
  -H "Authorization: Bearer $MAF_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: connector-telegram-v1" \
  -d '{
    "channel": "telegram",
    "credentials": { "bot_token": "'$TELEGRAM_BOT_TOKEN'" },
    "reply_with_voice": false
  }'

الحقلان reply_with_voice وdisplay_label الاختياري هما حقلان في المستوى الأعلى، وليسا داخل كائن config. يؤدي حفظ البوت أو الحساب نفسه مرة أخرى إلى تحديث بيانات اعتماده وإعداداته مع الحفاظ على رمز التوجيه الخاص به. في Telegram وInstagram، يؤدي استخدام بوت أو حساب مختلف إلى إضافة اتصال جديد بدلًا من ذلك (حتى خمسة اتصالات لكل وكيل)؛ أما في القنوات الأخرى فيستبدل الحفظ الاتصال الحالي. استخدم مصادقة API والنطاقات والأخطاء ومرجع API لمعرفة قواعد التكامل في بيئة الإنتاج.

الاختبار والمراقبة#

استخدم مستخدم اختبار لدى المزوّد وسؤالًا واقعيًا يعتمد على معرفة الوكيل. تأكد من كل ما يلي:

يقبل المزوّد نقطة نهاية webhook أو يتحقق منها.
تصل الرسالة إلى الوكيل وتتلقى الرد المتوقع.
يتغير آخر رسالة على بطاقة الموصّل.
تظهر المحادثة في المحادثات مع القناة الصحيحة.
فهم أي قيود مفروضة من المزوّد تتعلق بالمراجعة أو وضع التطوير قبل الإطلاق العام.
اختبار الصوت بشكل منفصل عن النص عندما تدعمه القناة.

تعرض بطاقة الموصّل آخر خطأ صادر عن المزوّد أو عن التسليم. كما تحتفظ لوحات تحكم المزوّدين بسجلات التسليم؛ قارن الطوابع الزمنية ومعرّفات الأحداث عندما يُبلغ أحد الطرفين فقط عن الطلب.

التعطيل أو التدوير أو الإزالة#

يؤدي التعطيل إلى إيقاف المعالجة مع الاحتفاظ بسجل الموصّل. يبقى webhook الخاص بـ Telegram مسجّلًا أثناء تعطيل الاتصال (لا يستدعي Make Agent Fast الدالة deleteWebhook) وتُتجاهل الرسائل الواردة؛ وعند التفعيل يُسجَّل الـ webhook من جديد. تبقى اشتراكات المزوّد التي أُعدّت عبر وحدة التحكم كما هي، ويجب إيقافها من جهة المزوّد أيضًا عند الحاجة. تؤدي الإزالة إلى حذف موصّل Make Agent Fast ومحاولة تفكيك الإعداد لدى المزوّد بأفضل جهد، لكنها لا تحذف التطبيق الخارجي، ولا تلغي بيانات اعتماده، ولا تمحو سجل المحادثات الحالي.

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

حالات الفشل الشائعة#

العَرَض	ما يجب التحقق منه
تعذّر التحقق من بيانات الاعتماد	صحة التطبيق/البوت، ونوع الرمز، وتاريخ الانتهاء، وصلاحية المزوّد المطلوبة، وسلامة الأحرف المنسوخة
فشل التحقق من webhook	عنوان HTTPS العام، ورمز التحقق (verify token) المطابق تمامًا، ومنتج المزوّد الصحيح، وسر توقيع الطلبات
ينجح التحقق لكن لا تصل أي رسائل	اشتراك الأحداث، وارتباط الصفحة/الرقم/القناة، ووضع تطبيق المزوّد، وحالة تفعيل الموصّل
يعمل النص لكن يفشل الصوت	إمكانات القناة، ومفتاح الكلام/النسخ الصوتي، والصوت المدعوم، وصلاحية الوسائط، وانتهاء صلاحية تنزيل المزوّد
تتوقف الردود بعد التدوير	حفظ بيانات الاعتماد الجديدة، وإلغاء القديمة بعد الاختبار فقط، وبقاء اشتراك المزوّد اليدوي موجّهًا إلى هذا الـ webhook

تابع مع دليل القناة لمعرفة حقول المزوّد الدقيقة وتسلسل الخطوات في وحدة التحكم.