REST API — автоматизуйте Telm зі свого коду

1Що дає API

Telm REST API дає вашому коду ті самі можливості, що й панель керування: проганяйте будь-який текст через антиспам-конвеєр, перевіряйте користувача Telegram, перш ніж впустити його, читайте й змінюйте налаштування захисту групи, керуйте власними правилами й білими списками, отримуйте журнал модерації та аналітику, а також реєструйте вебхуки для подій у реальному часі.

Так Telm перетворюється з бота, що живе у ваших групах, на інфраструктуру, яку можна під'єднати будь-де — до форми реєстрації на сайті, CRM-бота, ваших власних Telegram-ботів чи скрипта, що налаштовує сотню груп за раз.

• Базовий 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-ключем, а не сесією браузера, перевіряється на відповідність вашому тарифу й квоті, обробляється тим самим живим рушієм, що модерує ваші групи, і повертається як JSON.

Оскільки API звертається до того самого рушія й тих самих даних, що й бот, усе, що ви можете побачити чи змінити в панелі керування, можна зробити й у коді — а будь-яка зміна, зроблена в коді, одразу з'являється в панелі керування.

• Запити не зберігають стану: кожен несе власний ключ і не залежить від інших.
• Ключ діє від імені вашого акаунта й може торкатися лише груп, де ваш акаунт є адміном.
• Ендпоінт перевірки спаму звертається до того самого продакшн-конвеєра правил, тож вердикт API збігається з тим, що зробив би бот у групі.

3Автентифікація за допомогою API-ключів

Кожен запит автентифікується API-ключем вигляду tk_live_, за яким ідуть випадкові символи, — а не вашим логіном панелі керування. Ви створюєте ключі у своєму акаунті й надсилаєте ключ у заголовку Authorization як Bearer-токен або в заголовку X-API-Key.

Повний секрет показується один раз, у момент створення. Після цього панель керування показує ключ лише за коротким префіксом, щоб ви могли його впізнати, ніколи не зберігаючи повного значення. Якщо ключ витік, відкличте його та випустіть новий — відкликання набуває чинності одразу.

• Надсилайте ключ як Authorization: Bearer tk_live_your_key_here (заголовок X-API-Key теж працює).
• Ключі мають скоуп read або write: read — для GET-запитів, write — для всього, що змінює дані. Ключ лише для читання не може нічого створювати чи редагувати.
• Ви можете мати до десяти активних ключів одночасно, тож для кожного скрипта чи сервісу можна використовувати окремий ключ.
• Відсутній чи недійсний ключ повертає 401; ключ без потрібного скоупу повертає 403 insufficient_scope.

4Доступні ендпоінти

API побудовано навколо перевірок спаму й користувачів, керування групами та самообслуговування акаунта. Одиночний ендпоінт перевірки спаму відкритий для кожного тарифу; решта API входить до Pro та Business.

• POST /spam/check — прогнати один текст через той самий рушій правил, що модерує живий трафік (кожен тариф). На Pro і вище можна ввімкнути необов'язкову AI-перевірку.
• POST /spam/check-batch — перевірити до 20 текстів за один виклик, лише правила (Pro+).
• POST /users/check — перевірити користувача Telegram: статус 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 — керувати вебхуками подій у реальному часі (Pro+).
• GET /usage та GET /me — перевірити квоту й інформацію про ключ; ці виклики ніколи не витрачають квоту (кожен тариф).

5Ендпоінт перевірки спаму докладно

POST /spam/check — серце API і єдиний ендпоінт, який можна спробувати на будь-якому тарифі. Надішліть JSON-тіло з текстом для перевірки; відповідь повертає вердикт, числову оцінку, значення впевненості та рекомендовану дію, яку ви можете застосувати у власному продукті.

Один текст може мати до 10 000 символів. На Pro і вище для складніших випадків можна ввімкнути AI-перевірку, яка списується з окремого денного ліміту AI-перевірок. Для великих обсягів пакетний ендпоінт перевіряє до 20 текстів за один виклик і рахує квоту за кожен елемент.

• Використовуйте вердикт і оцінку, щоб вирішити, що робить ваш продукт: заблокувати надсилання форми, позначити лід чи автоматично видалити повідомлення у власному боті.
• Пакетний ендпоінт працює лише на правилах; AI-рівень доступний тільки в ендпоінті перевірки одного тексту.
• Розмір тіла запиту обмежено (приблизно 64 КБ для одиночної перевірки, 256 КБ для пакета); завеликі тіла повертають 413.

6Тарифи, ліміти частоти та денні квоти

Доступ вимірюється двома способами: похвилинним лімітом частоти (стеля сплеску) і денною квотою викликів, що скидається опівночі за UTC. Обидва рахуються на акаунт і спільні для всіх ваших API-ключів. Одиночний ендпоінт перевірки спаму можна спробувати на будь-якому тарифі, але повноцінна інтеграція з правилами, налаштуваннями, пакетними перевірками та вебхуками потребує Pro чи вище.

• Free — 100 викликів на день, лише перевірка спаму.
• Pro — 10 000 викликів на день, повний API та вебхуки, а також 1 000 AI-перевірок на день.
• Business — 50 000 викликів на день, повний API та вебхуки, а також 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 — у ключа немає скоупу write для виклику, що змінює дані.
• 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 показуйте пропозицію оновити тариф, а не повторюйте запит.
• Для реакцій у реальному часі віддавайте перевагу вебхукам, а не опитуванню — нехай Telm сам надсилає вам події.
• Періодично ротуйте ключі, а якщо ключ міг витекти, — негайно.

9Типові сценарії інтеграції

API використовують для значно більшого, ніж модерація повідомлень у Telegram.

• Реєстрація на сайті та в застосунку: проганяйте надісланий текст чи імена користувачів через POST /spam/check, перш ніж прийняти реєстрацію чи коментар.
• Ваші власні Telegram-боти: використовуйте антиспам-аналіз Telm у боті, яким Telm не керує, викликаючи ендпоінт перевірки зі свого обробника.
• Масове налаштування: застосовуйте скриптом однакові правила, білі списки та налаштування в десятках груп через ендпоінти налаштувань і правил.
• Дані та сповіщення: реєструйте вебхуки, щоб у реальному часі передавати події модерації в сховище даних, дашборд чи канал сповіщень.