REST API — אוטומציה של Telm מתוך הקוד שלכם

1מה ה-API מאפשר לכם לעשות

ה-REST API של Telm נותן לקוד שלכם את אותו טווח פעולה כמו לוח הבקרה: להעביר כל טקסט דרך צינור האנטי-ספאם, לבדוק משתמש טלגרם לפני שאתם מכניסים אותו, לקרוא ולשנות את הגדרות ההגנה של קבוצה, לנהל כללים מותאמים אישית ורשימות לבנות, למשוך את יומן המודרציה ואת האנליטיקה, ולרשום webhooks לאירועים בזמן אמת.

כך Telm הופכת מבוט שחי בתוך הקבוצות שלכם לתשתית שאפשר לחבר בכל מקום — טופס הרשמה באתר, בוט CRM, בוטי הטלגרם שלכם, או סקריפט שמגדיר מאה קבוצות בבת אחת.

• כתובת בסיס: api.telm.com/api/public/v1 — נתיב יציב עם גרסה (ה-v1 היא גרסת החוזה).
• כל בקשה וכל תגובה הן JSON מעל HTTPS.
• תיעוד אינטראקטיבי ומפרט OpenAPI 3.1 קריא-מכונה נמצאים בעמוד המפתחים — טענו את המפרט ל-Postman, למחולל קוד או לסוכן AI כדי להקים אינטגרציה תוך דקות.
• קריאות נמדדות מחזירות את הכותרות X-Quota-Limit, X-Quota-Used ו-X-Quota-Reset בכל תגובה.

2איך בקשה עוברת דרך Telm

ה-API הציבורי יושב על קידומת נתיב משלו, /api/public/, בנפרד מלוח הבקרה. כל קריאה מאומתת באמצעות מפתח API ולא באמצעות הפעלת דפדפן, נבדקת מול התוכנית והמכסה שלכם, רצה מול אותו מנוע חי שמבצע מודרציה בקבוצות שלכם, ומוחזרת כ-JSON.

מכיוון שה-API מגיע לאותו מנוע ולאותם נתונים כמו הבוט, כל מה שאתם יכולים לראות או לשנות בלוח הבקרה אפשר לעשות גם בקוד — וכל שינוי שתבצעו בקוד מופיע מיד בלוח הבקרה.

• הבקשות אינן שומרות מצב: כל אחת נושאת מפתח משלה ועומדת בפני עצמה.
• מפתח פועל בשם החשבון שלכם ויכול לגעת רק בקבוצות שבהן החשבון שלכם מנהל.
• נקודת הקצה לבדיקת ספאם מגיעה בדיוק לצינור הכללים של הפרודקשן, כך שפסק הדין של ה-API תואם את מה שהבוט היה עושה בקבוצה.

3אימות באמצעות מפתחות API

כל בקשה מאומתת באמצעות מפתח API בתבנית tk_live_ ואחריו תווים אקראיים — לא באמצעות ההתחברות שלכם ללוח הבקרה. אתם יוצרים מפתחות בחשבון שלכם ושולחים את המפתח בכותרת Authorization כטוקן Bearer, או בכותרת X-API-Key.

הסוד המלא מוצג פעם אחת, בזמן היצירה. לאחר מכן לוח הבקרה מציג מפתח רק לפי הקידומת הקצרה שלו, כך שתוכלו לזהות אותו בלי לשמור אי פעם את הערך המלא. אם מפתח דולף, בטלו אותו והנפיקו חדש — הביטול נכנס לתוקף מיד.

• שלחו את המפתח כ-Authorization: Bearer tk_live_your_key_here (גם כותרת X-API-Key עובדת).
• למפתחות יש היקף הרשאה של קריאה או כתיבה — קריאה לבקשות GET, כתיבה לכל מה שמשנה נתונים. מפתח לקריאה בלבד אינו יכול ליצור או לערוך.
• אפשר להחזיק עד עשרה מפתחות פעילים בבת אחת, כך שתוכלו להשתמש במפתח נפרד לכל סקריפט או שירות.
• מפתח חסר או לא תקף מחזיר 401; מפתח בלי היקף ההרשאה הנדרש מחזיר 403 insufficient_scope.

4נקודות הקצה הזמינות

ה-API מאורגן סביב בדיקות ספאם ומשתמשים, ניהול קבוצות ושירות עצמי לחשבון. נקודת הקצה הבודדת לבדיקת ספאם פתוחה לכל תוכנית; שאר ה-API הוא חלק מ-Pro ו-Business.

• POST /spam/check — מעבירה טקסט אחד דרך אותו מנוע כללים שמבצע מודרציה בתעבורה החיה (כל תוכנית). ב-Pro ומעלה אפשר להפעיל בדיקת AI אופציונלית.
• POST /spam/check-batch — בודקת עד 20 טקסטים בקריאה אחת, כללים בלבד (Pro+).
• POST /users/check — בדיקת משתמש טלגרם: סטטוס CAS, אותות מהחלטות הספאם של Telm והמוניטין בקבוצות שלכם (Pro+).
• GET /groups ו-GET /groups/{id} — רשימת הקבוצות שלכם וקריאתן (Pro+).
• GET ו-PATCH /groups/{id}/settings — קריאה ושינוי של הגדרות ההגנה של קבוצה (Pro+).
• GET/POST/PUT/DELETE /groups/{id}/rules — ניהול כללי מודרציה מותאמים אישית (Pro+).
• GET/POST/DELETE /groups/{id}/whitelist — ניהול הרשימה הלבנה של הקבוצה (Pro+).
• GET /groups/{id}/journal ו-GET /groups/{id}/analytics — קריאת יומן המודרציה והאנליטיקה (Pro+).
• GET/POST/PATCH/DELETE /webhooks — ניהול webhooks לאירועים בזמן אמת (Pro+).
• GET /usage ו-GET /me — בדיקת המכסה ופרטי המפתח שלכם; הן לעולם אינן צורכות מכסה (כל תוכנית).

5נקודת הקצה לבדיקת ספאם בפירוט

POST /spam/check היא הלב של ה-API ונקודת הקצה היחידה שאפשר לנסות בכל תוכנית. שלחו גוף JSON עם הטקסט לבדיקה; התגובה מחזירה פסק דין, ציון מספרי, ערך ביטחון ופעולה מומלצת שתוכלו להחיל במוצר שלכם.

טקסט בודד יכול להגיע עד 10,000 תווים. ב-Pro ומעלה אפשר לבחור בבדיקת AI למקרים קשים יותר, שנלקחת מקצבה יומית נפרדת של בדיקות AI. לנפח גבוה, נקודת הקצה של האצווה בודקת עד 20 טקסטים בקריאה אחת ומונה מכסה לכל פריט.

• השתמשו בפסק הדין ובציון כדי להחליט מה המוצר שלכם עושה — לחסום שליחת טופס, לסמן ליד, או להסיר הודעה אוטומטית בבוט שלכם.
• נקודת הקצה של האצווה מבוססת כללים בלבד; סולם ה-AI זמין רק בנקודת הקצה לטקסט בודד.
• גודל גוף הבקשה מוגבל (כ-64 KB לבדיקה בודדת, 256 KB לאצווה); גופים גדולים מדי מחזירים 413.

6תוכניות, מגבלות קצב ומכסות יומיות

הגישה נמדדת בשתי דרכים: מגבלת קצב לדקה (תקרת התפרצות) ומכסת קריאות יומית שמתאפסת בחצות UTC. שתיהן נספרות לכל חשבון ומשותפות לכל מפתחות ה-API שלכם. אפשר לנסות את נקודת הקצה הבודדת לבדיקת ספאם בכל תוכנית, אבל אינטגרציה אמיתית שנוגעת בכללים, בהגדרות, בבדיקות אצווה וב-webhooks דורשת Pro ומעלה.

• Free — 100 קריאות ליום, בדיקת ספאם בלבד.
• Pro — 10,000 קריאות ליום, API מלא ו-webhooks, ועוד 1,000 בדיקות AI ביום.
• Business — 50,000 קריאות ליום, API מלא ו-webhooks, ועוד 10,000 בדיקות AI ביום.
• גם מגבלות הקצב לדקה גדלות — 60 בקשות לדקה ב-Free, 600 ב-Pro ו-1,800 ב-Business.
• GET /usage ו-GET /me לעולם אינן נספרות במכסה שלכם, כך שתוכלו לבדוק את התקציב הנותר בכל עת.

7טיפול בשגיאות וקודי סטטוס

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

כשאתם חורגים מהמכסה היומית, קריאה נמדדת מחזירה 429 עם קוד daily_quota_exceeded, כותרת Retry-After וגוף שמפרט את התוכנית שלכם, המגבלה, מספר הקריאות שנוצלו, זמן האיפוס ורמז שדרוג. נקודות קצה שדורשות תוכנית גבוהה יותר מחזירות 403 plan_required עם התוכנית הנדרשת.

• 401 — מפתח API חסר או לא תקף.
• 403 plan_required — נקודת הקצה דורשת Pro ומעלה.
• 403 insufficient_scope — למפתח אין היקף הרשאת כתיבה עבור קריאה שמשנה נתונים.
• 429 daily_quota_exceeded או rate_limit_exceeded — המתינו לזמן האיפוס או שדרגו; כבדו את כותרת Retry-After.
• קראו את כותרות התגובה X-Quota-* כדי להקדים את המגבלה.

8שיטות עבודה מומלצות לאינטגרציה יציבה

כמה הרגלים שומרים על אינטגרציה אמינה ומאובטחת ככל שהיא גדלה.

• אחסנו מפתחות במנהל סודות, לעולם לא בקוד צד-לקוח או במאגר git; השתמשו במפתח נפרד לכל שירות כדי שתוכלו לבטל אחד בלי לשבור את האחרים.
• עקבו אחר הכותרות X-Quota-Used ו-X-Quota-Limit (או תשאלו את GET /usage) והאטו את הקצב לפני שאתם נתקלים בקיר, לא אחרי.
• ב-429, כבדו את Retry-After והאטו; ב-403 plan_required, הציגו הצעת שדרוג במקום לנסות שוב.
• לתגובות בזמן אמת, העדיפו webhooks על פני תשאול — תנו ל-Telm לדחוף אליכם אירועים.
• החליפו מפתחות מדי פעם, ומיד אם יש חשש שאחד מהם דלף.

9תרחישי אינטגרציה נפוצים

ה-API משמש להרבה יותר ממודרציה של הודעות טלגרם.

• הרשמה באתר ובאפליקציה: העבירו טקסט שנשלח או שמות משתמש דרך POST /spam/check לפני שאתם מאשרים הרשמה או תגובה.
• בוטי הטלגרם שלכם: נצלו את יכולות הזיהוי של Telm בבוט ש-Telm אינה מנהלת, באמצעות קריאה לנקודת הקצה של הבדיקה מתוך קוד הטיפול בהודעות של הבוט.
• הגדרה בכמויות: החילו בסקריפט את אותם כללים, רשימות לבנות והגדרות על עשרות קבוצות באמצעות נקודות הקצה של ההגדרות והכללים.
• נתונים והתראות: רשמו webhooks כדי להזרים אירועי מודרציה למחסן נתונים, ללוח מחוונים או לערוץ התראות בזמן אמת.