استكشاف الأخطاء: القنوات

مشاكل القنوات العامة

القناة تبدو متصلة لكن لا تصل رسائل

1. تحقق من معرّف المالك. إذا لم يكن ownerId مضبوطاً أو كان خاطئاً، قد تُوجَّه رسائلك كرسائل خارجية (غير مالك) بأذونات مقيّدة.
2. تحقق من التصنيف. إذا كان تصنيف القناة أقل من تلوث الجلسة، تُحظر الاستجابات بقاعدة عدم الكتابة للأسفل.
3. تحقق من سجلات الخدمة الخلفية. شغّل triggerfish logs --level WARN وابحث عن أخطاء التسليم.

الرسائل لا تُرسَل

يسجّل الموجّه فشل التسليم. تحقق من triggerfish logs بحثاً عن:

Channel send failed

هذا يعني أن الموجّه حاول التسليم لكن محول القناة أرجع خطأ. سيُسجَّل الخطأ المحدد بجانبه.

سلوك إعادة المحاولة

يستخدم موجّه القنوات تراجعاً أسياً للإرسال الفاشل. إذا فشلت رسالة، تُعاد المحاولة بتأخيرات متزايدة. بعد استنفاد جميع المحاولات، تُسقط الرسالة ويُسجَّل الخطأ.

---

Telegram

البوت لا يستجيب

1. تحقق من الرمز. اذهب إلى @BotFather على Telegram، تحقق من أن رمزك صالح ويطابق ما هو مخزّن في سلسلة المفاتيح.
2. راسل البوت مباشرة. تتطلب رسائل المجموعات أن يكون للبوت أذونات رسائل المجموعات.
3. تحقق من أخطاء الاستطلاع. يستخدم Telegram الاستطلاع الطويل. إذا انقطع الاتصال، يُعيد المحول الاتصال تلقائياً، لكن مشاكل الشبكة المستمرة ستمنع استلام الرسائل.

الرسائل تُقسَّم إلى أجزاء متعددة

لدى Telegram حد 4,096 حرف لكل رسالة. تُقسَّم الاستجابات الطويلة تلقائياً. هذا سلوك طبيعي.

أوامر البوت لا تظهر في القائمة

يُسجّل المحول أوامر slash عند بدء التشغيل. إذا فشل التسجيل، يسجّل تحذيراً لكنه يستمر في العمل. هذا غير مُعطِّل. البوت لا يزال يعمل؛ قائمة الأوامر فقط لن تعرض اقتراحات الإكمال التلقائي.

لا يمكن حذف الرسائل القديمة

لا يسمح Telegram للبوتات بحذف الرسائل الأقدم من 48 ساعة. محاولات حذف الرسائل القديمة تفشل بصمت. هذا قيد في واجهة Telegram API.

---

Slack

البوت لا يتصل

يتطلب Slack ثلاث بيانات اعتماد:

بيان الاعتماد	التنسيق	أين تجده
Bot Token	xoxb-...	صفحة OAuth & Permissions في إعدادات تطبيق Slack
App Token	xapp-...	Basic Information > App-Level Tokens
Signing Secret	سلسلة سداسية عشرية	Basic Information > App Credentials

إذا كان أي من الثلاثة مفقوداً أو غير صالح، يفشل الاتصال. الخطأ الأكثر شيوعاً هو نسيان App Token، المنفصل عن Bot Token.

مشاكل Socket Mode

يستخدم Triggerfish وضع Socket Mode الخاص بـ Slack، وليس اشتراكات أحداث HTTP. في إعدادات تطبيق Slack:

1. اذهب إلى "Socket Mode" وتأكد من تفعيله
2. أنشئ رمز مستوى التطبيق بنطاق connections:write
3. هذا الرمز هو appToken (xapp-...)

إذا لم يكن Socket Mode مُفعّلاً، رمز البوت وحده غير كافٍ للرسائل في الوقت الفعلي.

الرسائل تُقتطَع

لدى Slack حد 40,000 حرف. على عكس Telegram وDiscord، يقتطع Triggerfish رسائل Slack بدلاً من تقسيمها. إذا وصلت لهذا الحد بانتظام، فكّر في طلب إنتاج مخرجات أكثر إيجازاً من وكيلك.

تسريب موارد SDK في الاختبارات

يُسرّب Slack SDK عمليات غير متزامنة عند الاستيراد. هذه مشكلة معروفة في المصدر الأصلي. الاختبارات التي تستخدم محول Slack تحتاج sanitizeResources: false وsanitizeOps: false. لا يؤثر هذا على الاستخدام الإنتاجي.

---

Discord

البوت لا يستطيع قراءة الرسائل في الخوادم

يتطلب Discord intent مميز لـ Message Content. بدونه، يستقبل البوت أحداث الرسائل لكن محتوى الرسالة يكون فارغاً.

الحل: في بوابة مطوري Discord:

1. اختر تطبيقك
2. اذهب إلى إعدادات "Bot"
3. فعّل "Message Content Intent" تحت Privileged Gateway Intents
4. احفظ التغييرات

intents البوت المطلوبة

يتطلب المحول تفعيل هذه الـ intents:

• Guilds
• Guild Messages
• Direct Messages
• Message Content (مميز)

الرسائل تُقسَّم

لدى Discord حد 2,000 حرف. تُقسَّم الرسائل الطويلة تلقائياً إلى رسائل متعددة.

فشل مؤشر الكتابة

يرسل المحول مؤشرات كتابة قبل الاستجابات. إذا كان البوت يفتقر لإذن إرسال الرسائل في قناة، يفشل مؤشر الكتابة بصمت (يُسجَّل على مستوى DEBUG). هذا تجميلي فقط.

تسريب موارد SDK

مثل Slack، يُسرّب discord.js SDK عمليات غير متزامنة عند الاستيراد. الاختبارات تحتاج sanitizeOps: false. لا يؤثر هذا على الإنتاج.

---

WhatsApp

لا تُستقبَل رسائل

يستخدم WhatsApp نموذج webhook. يستمع البوت لطلبات HTTP POST الواردة من خوادم Meta. لوصول الرسائل:

1. سجّل عنوان URL الخاص بـ webhook في لوحة تحكم Meta Business
2. كوّن رمز التحقق. يُجري المحول مصافحة تحقق عند اتصال Meta لأول مرة
3. ابدأ مستمع webhook. يستمع المحول على المنفذ 8443 افتراضياً. تأكد من أن هذا المنفذ قابل للوصول من الإنترنت (استخدم وكيلاً عكسياً أو نفقاً)

تحذير "ownerPhone not configured"

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

الحل: اضبط رقم هاتف المالك في تكوينك:

channels:
  whatsapp:
    ownerPhone: "+1234567890"

انتهاء صلاحية رمز الوصول

يمكن أن تنتهي صلاحية رموز وصول WhatsApp Cloud API. إذا بدأت عمليات الإرسال بالفشل بأخطاء 401، أعد إنشاء الرمز في لوحة تحكم Meta وحدّثه:

triggerfish config set-secret whatsapp:accessToken <new-token>

---

Signal

signal-cli غير موجود

تتطلب قناة Signal تطبيق signal-cli، وهو تطبيق Java من طرف ثالث. يحاول Triggerfish تثبيته تلقائياً أثناء الإعداد، لكن هذا قد يفشل إذا:

• Java (JRE 21+) غير متوفر وفشل التثبيت التلقائي لـ JRE 25
• التنزيل حُظر بقيود الشبكة
• المجلد المستهدف غير قابل للكتابة

التثبيت اليدوي:

# ثبّت signal-cli يدوياً
# راجع https://github.com/AsamK/signal-cli للتعليمات

خدمة signal-cli غير قابلة للوصول

بعد بدء signal-cli، ينتظر Triggerfish حتى 60 ثانية ليصبح قابلاً للوصول. إذا انتهت المهلة:

signal-cli daemon (tcp) not reachable within 60s

تحقق من:

1. هل signal-cli يعمل فعلاً؟ تحقق من ps aux | grep signal-cli
2. هل يستمع على نقطة النهاية المتوقعة (مقبس TCP أو مقبس Unix)؟
3. هل حساب Signal يحتاج إلى ربط؟ شغّل triggerfish config add-channel signal لإعادة عملية الربط.

فشل ربط الجهاز

يتطلب Signal ربط الجهاز بحساب Signal الخاص بك عبر رمز QR. إذا فشلت عملية الربط:

1. تأكد من تثبيت Signal على هاتفك
2. افتح Signal > الإعدادات > الأجهزة المرتبطة > ربط جهاز جديد
3. امسح رمز QR المعروض بواسطة معالج الإعداد
4. إذا انتهت صلاحية رمز QR، أعد عملية الربط

عدم تطابق إصدار signal-cli

يُثبّت Triggerfish إصداراً معروفاً بالعمل الجيد من signal-cli. إذا ثبّتت إصداراً مختلفاً، قد ترى تحذيراً:

Signal CLI version older than known-good

هذا غير مُعطِّل لكنه قد يسبب مشاكل توافقية.

---

Email

فشل اتصال IMAP

يتصل محول البريد الإلكتروني بخادم IMAP للبريد الوارد. المشاكل الشائعة:

• بيانات اعتماد خاطئة. تحقق من اسم المستخدم وكلمة المرور لـ IMAP.
• المنفذ 993 محظور. يستخدم المحول IMAP عبر TLS (المنفذ 993). بعض الشبكات تحظر هذا.
• كلمة مرور خاصة بالتطبيق مطلوبة. Gmail ومزودون آخرون يتطلبون كلمات مرور خاصة بالتطبيق عند تفعيل المصادقة الثنائية.

رسائل الخطأ التي قد تراها:

• IMAP LOGIN failed - اسم مستخدم أو كلمة مرور خاطئة
• IMAP connection not established - لا يمكن الوصول إلى الخادم
• IMAP connection closed unexpectedly - الخادم أسقط الاتصال

فشل إرسال SMTP

يرسل محول البريد الإلكتروني عبر واجهة SMTP API relay (وليس SMTP المباشر). إذا فشلت عمليات الإرسال بأخطاء HTTP:

• 401/403: مفتاح API غير صالح
• 429: تحديد معدل
• 5xx: خدمة الترحيل معطّلة

توقف استطلاع IMAP

يستطلع المحول رسائل البريد الجديدة كل 30 ثانية. إذا فشل الاستطلاع، يُسجَّل الخطأ لكن لا يوجد إعادة اتصال تلقائية. أعد تشغيل الخدمة الخلفية لإعادة إنشاء اتصال IMAP.

هذا قيد معروف. راجع المشكلات المعروفة.

---

WebChat

رُفضت ترقية WebSocket

يتحقق محول WebChat من الاتصالات الواردة:

• الرؤوس كبيرة جداً (431). حجم الرأس المجمّع يتجاوز 8,192 بايت. يمكن أن يحدث هذا مع ملفات تعريف الارتباط الكبيرة جداً أو الرؤوس المخصصة.
• رفض CORS. إذا كان allowedOrigins مكوّناً، يجب أن يتطابق رأس Origin. الافتراضي هو ["*"] (السماح للجميع).
• إطارات مشوّهة. JSON غير صالح في إطارات WebSocket يُسجَّل على مستوى WARN ويُسقط الإطار.

التصنيف

يُصنَّف WebChat افتراضياً كـ PUBLIC. لا يُعامَل الزوار أبداً كمالك. إذا احتجت تصنيفاً أعلى لـ WebChat، اضبطه صراحة:

channels:
  webchat:
    classification: INTERNAL

---

Google Chat

فشل استطلاع PubSub

يستخدم Google Chat خدمة Pub/Sub لتسليم الرسائل. إذا فشل الاستطلاع:

Google Chat PubSub poll failed

تحقق من:

• بيانات اعتماد Google Cloud صالحة (تحقق من credentials_ref في التكوين)
• اشتراك Pub/Sub موجود ولم يُحذف
• حساب الخدمة لديه دور pubsub.subscriber

رُفضت رسائل المجموعة

إذا لم يُكوَّن وضع المجموعة، قد تُسقط رسائل المجموعة بصمت:

Google Chat group message denied by group mode

كوّن defaultGroupMode في تكوين قناة Google Chat.

ownerEmail غير مكوَّن

بدون ownerEmail، يُعامَل جميع المستخدمين كغير مالك:

Google Chat ownerEmail not configured, defaulting to non-owner

اضبطه في تكوينك للحصول على وصول كامل للأدوات.