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

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

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

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

• Base URL: 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 ולא session של דפדפן, נבדקת מול התוכנית והמכסה שלכם, מורצת מול אותו מנוע חי שמנהל מודרציה בקבוצות שלכם, ומוחזרת כ-JSON.

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

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

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

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

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

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

4Endpoints זמינים

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

• POST /spam/check — הריצו טקסט אחד דרך אותו מנוע כללים שמנהל מודרציה בתעבורה חיה (כל תוכנית). ניתן להפעיל בדיקת AI אופציונלית ב-Pro ומעלה.
• 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 — בדקו את המכסה ומידע המפתח שלכם; אלה לעולם אינם צורכים מכסה (כל תוכנית).

5endpoint בדיקת הספאם בפירוט

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

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

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

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

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

• Free — 100 קריאות/יום, בדיקת ספאם בלבד.
• Basic — 1,000 קריאות/יום, בדיקת ספאם בלבד.
• Pro — 10,000 קריאות/יום, API מלא ו-webhooks, בתוספת מכסת בדיקות-AI יומית.
• Business — 50,000 קריאות/יום, API מלא ו-webhooks, מכסת AI גדולה יותר.
• מגבלות הקצב לדקה משתנות גם הן — תוכניות גבוהות מקבלות תקרת פרץ גדולה בהרבה.

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

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

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

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

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

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

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

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

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

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