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

1Что позволяет делать API

REST API Telm даёт вашему собственному коду тот же охват, что и дашборд: прогнать любой текст через конвейер антиспама, проверить пользователя 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 организован вокруг проверок спама и пользователей, управления группами и самообслуживания аккаунта. Единственный эндпоинт проверки спама открыт для каждого тарифа; остальная часть поверхности входит в Pro и Business.

• POST /spam/check — прогнать один текст через тот же движок правил, что модерирует живой трафик (каждый тариф). Необязательная проверка AI доступна с Basic (квота: 100/день, Pro 1 000, Business 10 000).
• 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 KB для одной проверки, 256 KB для пакета); слишком большие тела возвращают 413.

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

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

• Free — 100 вызовов/день, только проверка спама.
• Basic — 1 000 вызовов/день, только проверка спама.
• Pro — 10 000 вызовов/день, полный API и вебхуки, плюс дневной лимит AI-проверок.
• Business — 50 000 вызовов/день, полный API и вебхуки, больший лимит AI.
• Лимиты частоты в минуту тоже растут — более высокие тарифы получают гораздо больший потолок всплеска.

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 не управляет, вызывая эндпоинт проверки из своего обработчика.
• Массовая настройка: скриптуйте одни и те же правила, белые списки и настройки по десяткам групп с помощью эндпоинтов настроек и правил.
• Данные и оповещения: регистрируйте вебхуки, чтобы транслировать события модерации в хранилище данных, дашборд или канал оповещений в реальном времени.