פתרון בעיות: ערוצים

בעיות ערוץ כלליות

ערוץ נראה מחובר אך אין הודעות מגיעות

1. בדקו את מזהה הבעלים. אם ownerId אינו מוגדר או שגוי, הודעות מכם עשויות להיות מנותבות כהודעות חיצוניות (לא-בעלים) עם הרשאות מוגבלות.
2. בדקו סיווג. אם סיווג הערוץ נמוך מזיהום הסשן, תגובות נחסמות על ידי כלל אין-כתיבה-למטה.
3. בדקו את לוגי ה-daemon. הריצו triggerfish logs --level WARN וחפשו שגיאות מסירה.

הודעות אינן נשלחות

הנתב מתעד כשלי מסירה. בדקו triggerfish logs עבור:

Channel send failed

זה אומר שהנתב ניסה מסירה אך מתאם הערוץ החזיר שגיאה. השגיאה הספציפית תתועד לצדה.

התנהגות ניסיון חוזר

נתב הערוצים משתמש ב-backoff אקספוננציאלי עבור שליחות שנכשלו. אם הודעה נכשלת, היא ניסתנית מחדש עם השהיות הולכות וגדלות. לאחר שכל הניסיונות החוזרים מוצו, ההודעה נזרקת והשגיאה מתועדת.

---

Telegram

בוט אינו מגיב

1. ודאו את הטוקן. היכנסו ל-@BotFather ב-Telegram, בדקו שהטוקן שלכם תקף ותואם למה שמאוחסן ב-keychain.
2. שלחו הודעה ישירה לבוט. הודעות קבוצתיות דורשות שלבוט תהיה הרשאת הודעות קבוצתיות.
3. בדקו שגיאות polling. Telegram משתמש ב-long polling. אם החיבור נופל, המתאם מתחבר מחדש אוטומטית, אבל בעיות רשת מתמשכות ימנעו קבלת הודעות.

הודעות מפוצלות למספר חלקים

ל-Telegram יש מגבלה של 4,096 תווים להודעה. תגובות ארוכות מחולקות אוטומטית. זו התנהגות רגילה.

פקודות בוט לא מופיעות בתפריט

המתאם רושם פקודות slash בהפעלה. אם הרישום נכשל, הוא מתעד אזהרה אך ממשיך לרוץ. זה לא קריטי. הבוט עדיין עובד; תפריט הפקודות פשוט לא יציג הצעות השלמה אוטומטית.

לא ניתן למחוק הודעות ישנות

Telegram אינו מאפשר לבוטים למחוק הודעות ישנות מ-48 שעות. ניסיונות למחוק הודעות ישנות נכשלים בשקט. זו מגבלה של API של Telegram.

---

Slack

בוט אינו מתחבר

Slack דורש שלושה אישורים:

אישור	פורמט	היכן למצוא
Bot Token	xoxb-...	דף OAuth & Permissions בהגדרות אפליקציית Slack
App Token	xapp-...	Basic Information > App-Level Tokens
Signing Secret	מחרוזת Hex	Basic Information > App Credentials

אם אחד מהשלושה חסר או לא תקף, החיבור נכשל. הטעות הנפוצה ביותר היא שכחת App Token, שהוא נפרד מ-Bot Token.

בעיות Socket Mode

Triggerfish משתמש ב-Socket Mode של Slack, לא במנויי אירועי HTTP. בהגדרות אפליקציית Slack שלכם:

1. היכנסו ל-"Socket Mode" וודאו שהוא מופעל
2. צרו app-level token עם scope של connections:write
3. טוקן זה הוא ה-appToken (xapp-...)

אם Socket Mode אינו מופעל, ה-bot token לבדו אינו מספיק להודעות בזמן אמת.

הודעות נחתכות

ל-Slack יש מגבלה של 40,000 תווים. בניגוד ל-Telegram ו-Discord, Triggerfish חותך הודעות Slack במקום לפצל אותן. אם אתם נתקלים במגבלה זו באופן קבוע, שקלו לבקש מהסוכן שלכם לייצר פלט תמציתי יותר.

דליפות משאבי SDK בבדיקות

SDK של Slack מדליף פעולות אסינכרוניות בעת ייבוא. זו בעיה ידועה ב-upstream. בדיקות המשתמשות במתאם Slack צריכות sanitizeResources: false ו-sanitizeOps: false. זה אינו משפיע על שימוש בייצור.

---

Discord

בוט אינו יכול לקרוא הודעות בשרתים

Discord דורש את ה-Message Content privileged intent. בלעדיו, הבוט מקבל אירועי הודעה אבל תוכן ההודעה ריק.

תיקון: ב-Discord Developer Portal:

1. בחרו את האפליקציה שלכם
2. היכנסו להגדרות "Bot"
3. הפעילו "Message Content Intent" תחת Privileged Gateway Intents
4. שמרו שינויים

intents נדרשים לבוט

המתאם דורש intents אלו מופעלים:

• Guilds
• Guild Messages
• Direct Messages
• Message Content (privileged)

הודעות מחולקות

ל-Discord יש מגבלה של 2,000 תווים. הודעות ארוכות מפוצלות אוטומטית למספר הודעות.

מחוון הקלדה נכשל

המתאם שולח מחווני הקלדה לפני תגובות. אם לבוט אין הרשאה לשלוח הודעות בערוץ, מחוון ההקלדה נכשל בשקט (מתועד ברמת DEBUG). זה קוסמטי בלבד.

דליפות משאבי SDK

כמו Slack, SDK של discord.js מדליף פעולות אסינכרוניות בעת ייבוא. בדיקות צריכות sanitizeOps: false. זה אינו משפיע על ייצור.

---

WhatsApp

לא מתקבלות הודעות

WhatsApp משתמש במודל webhook. הבוט מאזין לבקשות HTTP POST נכנסות משרתי Meta. כדי שהודעות יגיעו:

1. רשמו את כתובת ה-webhook ב-Meta Business Dashboard
2. הגדירו את verify token. המתאם מריץ לחיצת יד אימות כש-Meta מתחבר לראשונה
3. הפעילו את מאזין ה-webhook. המתאם מאזין בפורט 8443 כברירת מחדל. ודאו שפורט זה נגיש מהאינטרנט (השתמשו ב-reverse proxy או מנהרה)

אזהרת "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 socket או Unix socket)?
3. האם חשבון Signal צריך קישור? הריצו triggerfish config add-channel signal כדי לעבור שוב את תהליך הקישור.

קישור מכשיר נכשל

Signal דורש קישור המכשיר לחשבון Signal שלכם דרך קוד QR. אם תהליך הקישור נכשל:

1. ודאו ש-Signal מותקן בטלפון שלכם
2. פתחו Signal > Settings > Linked Devices > Link New Device
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 וספקים אחרים דורשים סיסמאות ספציפיות לאפליקציה כאשר 2FA מופעל.

הודעות שגיאה שעשויות להופיע:

• IMAP LOGIN failed - שם משתמש או סיסמה שגויים
• IMAP connection not established - לא ניתן להגיע לשרת
• IMAP connection closed unexpectedly - השרת ניתק את החיבור

כשלי שליחת SMTP

מתאם האימייל שולח דרך relay API של SMTP (לא SMTP ישיר). אם שליחות נכשלות עם שגיאות HTTP:

• 401/403: מפתח API לא תקף
• 429: הגבלת קצב
• 5xx: שירות ה-relay מושבת

סקירת IMAP נעצרת

המתאם סורק אימיילים חדשים כל 30 שניות. אם הסקירה נכשלת, השגיאה מתועדת אך אין חיבור מחדש אוטומטי. אתחלו מחדש את ה-daemon כדי ליצור מחדש את חיבור ה-IMAP.

זו מגבלה ידועה. ראו בעיות ידועות.

---

WebChat

שדרוג WebSocket נדחה

מתאם WebChat מאמת חיבורים נכנסים:

• כותרות גדולות מדי (431). גודל הכותרות המשולב חורג מ-8,192 בתים. זה יכול לקרות עם cookies גדולים מדי או כותרות מותאמות.
• דחיית 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

הגדירו אותו בתצורה שלכם כדי לקבל גישה מלאה לכלים.