1מה כל תוכנית כוללת
קו החלוקה פשוט. בדיקת ספאם בטקסט זמינה בכל תוכנית, כך שאפילו השכבה החינמית יכולה להשתמש בזיהוי של Telm כמסנן במוצר שלה. מלוא היכולות — סינון משתמשים עם רמות סיכון, יומן ההחלטות והאנליטיקה, ניהול הגדרות וכללים, ו-Webhooks — הוא חלק מתוכניות Pro ו-Business.
כל תוכנית מקבלת מכסת בקשות יומית, בגודל שמניח אינטגרציות כבדות יותר על תוכניות כבדות יותר:
- **Free** — 100 בקשות API ליום, בדיקת ספאם בלבד.
- **Basic** — 1,000 בקשות API ליום, בדיקת ספאם בלבד.
- **Pro** — 10,000 בקשות API ליום, בתוספת ה-API המלא וה-Webhooks.
- **Business** — 50,000 בקשות API ליום, בתוספת ה-API המלא וה-Webhooks.
- צרו את המפתחות שלכם תחת Settings → API & Webhooks, שמרו אותם במאגר הסודות שלכם, אמתו את החתימה של כל Webhook, ואותו מנוע ששומר על הקבוצות שלכם הופך לחלק מהמחסנית שלכם.
2רישום שאפשר לתשאל של כל החלטה
כל מה שהמנוע מחליט נרשם, ו-`GET journal` מוסר את הרישום הזה לקוד שלכם. כל רשומה היא החלטה אחת: הפסק, הציון שמאחוריו, אילו כללים הופעלו, והפעולה שבאה בעקבותיהם. מכיוון שהוא בדפדוף מבוסס סמן, אתם יכולים לצעוד לאורך כל ההיסטוריה באמינות — עמוד אחר עמוד, ללא פערים או כפילויות — ולמשוך אותה לכל מקום שבו אתם שומרים רשומות.
זה הופך את היומן לעמוד השדרה של ארכיון ציות. צוותים שנדרשים להראות מדוע חבר הוסר — עבור מדיניות פלטפורמה, חוזה לקוח או רגולטור — מייצאים את היומן למאגר ארוך-הטווח שלהם בלוח זמנים, ומעניקים לעצמם דין וחשבון עצמאי הניתן לתשאול על כל פעולת אכיפה שאינו תלוי בגלילה אחורה בטלגרם. אלו אותן ראיות שה-יומן הביקורת של לוח הבקרה מציג לבני אדם, זמינות למערכות שלכם.
לצדו, נקודת קצה של אנליטיקה מחזירה סדרות יום-אחר-יום — נפחים ומגמות לאורך זמן — כך שתוכלו למפות את עומס המודרציה בכלי הבינה העסקית שלכם לצד כל מה שאתם עוקבים אחריו, במקום לקרוא אותו ממסך. גם היומן וגם האנליטיקה הם חלק מתוכניות Pro ו-Business.
3מסירה שאפשר לסמוך עליה
מודל דחיפה אמין רק אם הוא מתמודד עם הפעמים שנקודת הקצה שלכם איטית, מופעלת מחדש או מושבתת לרגע — וזה של Telm מתמודד. המסירה היא לפחות-פעם-אחת: כל אירוע נושא `id` יציב, ו-Telm ממשיכה לנסות עד שנקודת הקצה שלכם מאשרת אותו. מכיוון שלפחות-פעם-אחת אומר שאותו אירוע יכול להגיע כדין פעמיים, מנעו כפילויות לפי אותו `id` — רשמו את אלה שעיבדתם והתעלמו מחזרות — וההתנהלות שלכם נשארת נכונה ללא קשר לכמה פעמים משלוח מנוסה מחדש.
הניסיונות החוזרים עוקבים אחר לוח זמנים מתרחב במקום להלום נקודת קצה מתקשה: מיד, ואז אחרי דקה, חמש דקות, שלושים דקות, שעתיים ושש שעות — שישה ניסיונות בסך הכול, פרושים כדי לתת לשירות מתאושש מקום לחזור. אם נקודת קצה נשארת שבורה — עשרים כשלים רצופים ושבעים ושתיים שעות ללא מסירה מוצלחת — Telm מפסיקה לשלוח אליה אוטומטית ומודיעה לכם בטלגרם, כך שכתובת מתה הופכת להתראה ברורה לתקן את המקבל שלכם במקום סילון שקט של כשלים שנערמים.
כדי לבנות אינטגרציה חדשה נכון, אינכם צריכים לעורר אירועים אמיתיים כדי לבדוק אותה. פינג בדיקה מאפשר לכם לירות משלוח לדוגמה אל נקודת הקצה שלכם לפי דרישה ולאמת שבדיקת החתימה והמטפל שלכם עובדים, והיסטוריית משלוח מציגה מה נשלח ואיך התנהל כל ניסיון — כך שתוכלו לנפות באגים במקבל בעייתי מתוך הרישום במקום לנחש.
4מודרציה שמדברת עם שאר המחסנית שלכם
בוט מודרציה שחי כולו בתוך טלגרם הוא שימושי, אבל הוא גם אי. ההחלטות שהוא מקבל — כל הודעה שהוא מסיר, כל משתמש שהוא מסנן, כל פשיטה שהוא הודף — נשארות נעולות בחלון צ'אט אלא אם מישהו פותח את טלגרם כדי להביט. עבור קהילה בודדת זה בסדר. עבור צוות שמנהל מודרציה כחלק ממערך גדול יותר, זה אומר שהמערכת האחת שיודעת הכי הרבה על מי מנצל את המרחבים שלכם היא המערכת האחת שאינה יכולה לדבר עם שום דבר אחר שאתם מפעילים.
ה-REST API הציבורי וה-Webhooks סוגרים את הפער הזה. הם הופכים את Telm מבוט עצמאי לרכיב שאתם יכולים לחבר לכלים שכבר יש לכם: מערך הניטור והכוננות, ארכיון הציות, המוצר שלכם, לוחות הבקרה הפנימיים. אותו מנוע שמגן על הקבוצות שלכם הופך למשהו שהמערכות האחרות שלכם יכולות לתשאל, להאזין לו ולהניע.
מדריך זה עובר על מה שה-API וה-Webhooks חושפים בפועל — נקודות הקצה, האירועים, מודל האבטחה — ועל הדברים הקונקרטיים שצוותים בונים איתם. כל מה שלמטה הוא יכולת אמיתית זמינה היום; אין SDK להמתין לו ואין דבר המתואר כאן שהמוצר רק מתכנן לעשות.
5סינון טקסטים ומשתמשים לפי דרישה
שתי נקודות קצה מאפשרות לכם להריץ את שיקול הדעת של Telm לפי דרישה, מהקוד שלכם, בלי שהודעה תעבור אי-פעם דרך קבוצת טלגרם.
`POST /spam/check` שולח קטע טקסט דרך אותו מנוע ייצורי בדיוק ששומר על הקהילות שלכם — אותות השולחים המשותפים, כללי התבניות, המסווגים — ומחזיר פסק. זו הקריאה האחת הזמינה בכל תוכנית, מה שהופך אותה למסנן ספאם טבעי למוצר שלכם: סננו תגובות, ביוגרפיות של הרשמה, פניות תמיכה או פרסומי שוק עם אותו זיהוי שמגן על מרחבי הטלגרם שלכם. הוסיפו `include_ai` כדי לשלב פסק בינה מלאכותית עבור המקרים הקשים והמעורפלים יותר (זמין ב-Pro וב-Business), ובתוכניות אלה תוכלו לקבץ עד עשרים טקסטים בבקשה אחת במקום לקרוא פעם לכל פריט.
`POST /users/check` מסנן אדם ולא הודעה. הוא משלב את רשימת החסימה הגלובלית CAS, את מסד הנתונים של Telm עצמה שנבנה ממודרציה על פני קהילות רבות, ומחזיר רמת סיכון (ב-Pro וב-Business) כדי שתוכלו להחליט כמה חיכוך להפעיל — העבירו חשבון נקי היישר, החזיקו חשבון מסוכן לבדיקה. חיבורו לתהליך ההצטרפות שלכם מאפשר לכם לתפוס שחקן רע ידוע בפתח האתר או האפליקציה שלכם, ולא רק אחרי שהצטרף לקבוצת טלגרם.
שתי הקריאות עונות בתוך השורה: אתם שולחים את הטקסט או את המשתמש, אתם מקבלים את ההערכה בחזרה בתגובה. אין תור לתשאול ואין callback להמתין לו — ההחלטה מגיעה עם המענה.
6לקבל דחיפה ברגע שזה קורה
תשאול היומן מתאים לארכוב, אך כשאתם רוצים *להגיב* למשהו ברגע שהוא מתרחש, אתם רוצים לקבל דחיפה, לא לשאול. Webhooks (ב-Pro וב-Business) עושים בדיוק את זה: אתם רושמים נקודת קצה, ו-Telm שולחת אליה בקשת HTTP ברגע שאירוע רלוונטי מופעל. האירועים מכסים את הרגעים שחשובים — `spam.detected` ו-`message.suspicious` לתוכן, ו-`user.banned`, `user.kicked`, `user.muted`, `user.joined` ו-`user.left` לחברות.
השימוש המובן מאליו הוא הפיכת גל ספאם להתראה. כוונו את `spam.detected` אל מערכת הניטור או הכוננות שלכם וזינוק פתאומי הופך לזימון של מי שתורן, באותו מקום שבו נוחתים שאר האירועים שלכם — איש אינו צריך לצפות בטלגרם כדי להבחין במתקפה שמתחילה. אותו זרם מזין לוחות בקרה בזמן אמת, שומר מערכת חיצונית מסונכרנת עם חסימות, או מפעיל כל תהליך עבודה שתרצו.
מכיוון שהבקשות האלה מגיעות מהעולם החיצון אל התשתית שלכם, כל משלוח חתום. כל בקשה נושאת כותרת `X-Telm-Signature` מהצורה `v1=hex(hmac_sha256(secret, "timestamp.body"))` — HMAC-SHA256 על חותמת הזמן והגוף הגולמי, ממופתח בסוד שרק אתם ו-Telm חולקים. חישוב מחדש של אותה חתימה בצד שלכם מוכיח שהבקשה באמת הגיעה מ-Telm ולא זויפה או שונתה בדרך; חותמת הזמן מאפשרת לכם לדחות שליחות חוזרות ישנות. אמתו את החתימה לפני שאתם בוטחים במטען — אלו כמה שורות קוד והצעד החשוב ביותר במקבל Webhook בטוח.
7ה-REST API והמפתחות שלכם
ה-API שוכן בכתובת `https://api.telm.com/api/public/v1`. זהו ממשק REST פשוט — אתם קוראים לו בבקשות HTTPS רגילות וב-JSON, מכל שפה, ללא ספריית לקוח מיוחדת. אם הקוד שלכם יכול לבצע בקשת HTTP, הוא יכול לדבר עם Telm.
האימות מתבצע באמצעות מפתח API. אתם יוצרים מפתחות בלוח הבקרה תחת Settings → API & Webhooks, וכל אחד מוצג לכם בדיוק פעם אחת בעת היצירה — העתיקו אותו למאגר הסודות שלכם שם ואז, כי אי אפשר לאחזר אותו שוב לאחר מכן. המפתחות נושאים את הקידומת `tk_live_` כך שקל לזהות אותם ביומנים ובתצורה. כל מפתח נושא הרשאה — קריאה או כתיבה — כך ששירות שצריך רק למשוך את יומן ההחלטות יכול להחזיק מפתח לקריאה בלבד, בעוד אוטומציה שמשנה הגדרות מקבלת מפתח כתיבה. הנפיקו מפתח אחד לכל מערכת, וביטול מפתח שדלף או פרש לעולם אינו מפריע לאחרים.
השימוש נשלט על ידי מכסת בקשות יומית הקשורה לתוכנית שלכם, כך שהתפוקה צפויה ותסריט אחד שיצא משליטה אינו יכול למצות הכול. הבדיקה הקלה ביותר — סריקת ספאם בטקסט — זמינה בכל תוכנית בגבולות אותה מכסה; מערך היכולות הרחב יותר, מיומן ההחלטות ועד ניהול הגדרות ו-Webhooks, הוא חלק מתוכניות Pro ו-Business. המספרים המדויקים מפורטים בסוף.
8ניהול קבוצות רבות מקוד
ה-API אינו רק קורא ומאזין — הוא כותב. ב-Pro וב-Business אתם יכולים לבצע `PATCH` על הגדרות של קבוצה ולהריץ יצירה/קריאה/עדכון/מחיקה מלאה על הכללים ועל הרשימה הלבנה שלה, הכול באופן תכנותי. כל דבר שהייתם מגדירים ידנית בלוח הבקרה, אתם יכולים להגדיר מתסריט.
זה מה שהופך ניהול מודרציה בקנה מידה גדול למעשי. סוכנות או מפעיל גדול שמנהל עשרות קהילות אינו רוצה לפתוח כל אחת וללחוץ דרך אותם שינויים; הם רוצים להגדיר את המדיניות פעם אחת וליישם אותה בכל מקום. עם ה-API אתם משיקים כלל חדש, מכווננים סף, או מוסיפים כתובת לכל רשימה לבנה על פני הצי כולו במעבר אוטומטי אחד, ושומרים את הקבוצות מסונכרנות ככל שהסטנדרטים שלכם מתפתחים.
זה גם מאפשר למדיניות המודרציה לחיות בבקרת המקור שלכם. שמרו את התצורה הרצויה כקוד, יישמו אותה דרך ה-API, וכל שינוי באופן שבו הקבוצות שלכם מנוהלות נבדק ומנוהל בגרסאות כמו שאר התשתית שלכם — רחוק מאוד מהצורך לזכור אילו הגדרות שיניתם באיזה צ'אט.