1Модерация, которая говорит с остальным вашим стеком
Бот модерации, живущий целиком внутри Telegram, полезен — но он ещё и остров. Его решения — каждое удалённое сообщение, каждый проверенный пользователь, каждый отражённый налёт — заперты в окне чата, пока кто-нибудь не откроет Telegram и не заглянет туда. Для одного сообщества это нормально. Для команды, у которой модерация — часть большой операции, это значит, что система, знающая больше всех о тех, кто злоупотребляет вашими пространствами, — единственная, которая не умеет общаться ни с чем другим в вашем хозяйстве.
Публичный REST API и вебхуки закрывают этот разрыв. Они превращают Telm из самодостаточного бота в компонент, который можно встроить в уже имеющиеся инструменты: ваш мониторинг и дежурства, архив для комплаенса, ваш собственный продукт, внутренние дашборды. Тот же движок, что защищает ваши группы, становится тем, что другие ваши системы могут опрашивать, слушать и приводить в действие.
Этот гайд разбирает, что на самом деле открывают API и вебхуки — эндпоинты, события, модель безопасности — и что конкретно на них строят команды. Всё, что ниже, — реальная возможность, доступная уже сегодня; не нужно ждать никакого SDK, и здесь нет ничего, что продукт лишь собирается сделать.
2REST API и ваши ключи
API живёт по адресу `https://api.telm.com/api/public/v1`. Это обычный REST-интерфейс — вы обращаетесь к нему простыми HTTPS-запросами и JSON, с любого языка, без специальной клиентской библиотеки. Если ваш код умеет делать HTTP-запрос, он умеет общаться с Telm.
Аутентификация — по API-ключу. Ключи создаются в дашборде, в разделе «Настройки → API и вебхуки», и каждый показывается ровно один раз при создании — скопируйте его в своё хранилище секретов сразу же, потому что потом получить его снова нельзя. Ключи начинаются с префикса `tk_live_`, чтобы их было легко узнать в логах и конфигах. У каждого ключа есть scope — на чтение или на запись, — так что сервису, которому нужно лишь выгружать журнал решений, достаточно ключа только на чтение, а автоматизация, меняющая настройки, получает ключ на запись. Заведите по одному ключу на систему — и отзыв утёкшего или отслужившего ключа никогда не заденет остальные.
Использование ограничено дневной квотой запросов, привязанной к вашему плану, так что пропускная способность предсказуема, а один сорвавшийся скрипт не выберет всё разом. Самая лёгкая проверка — сканирование текста на спам — доступна на любом плане в пределах этой квоты; более полная поверхность, от журнала решений до управления настройками и вебхуков, входит в планы Pro и Business. Точные цифры приведены в конце.
3Проверка текста и пользователей по запросу
Два эндпоинта позволяют получить вердикт Telm по запросу, из собственного кода, без того чтобы сообщение вообще проходило через Telegram-группу.
`POST /spam/check` пропускает фрагмент текста через тот самый боевой движок, что охраняет ваши сообщества, — общие сигналы о спамерах, правила-паттерны, классификаторы — и возвращает вердикт. Это единственный вызов, доступный на любом плане, что делает его естественным спам-фильтром для вашего собственного продукта: проверяйте комментарии, анкеты при регистрации, тикеты поддержки или объявления на маркетплейсе той же детекцией, что защищает ваши пространства в Telegram. Добавьте `include_ai`, чтобы подмешать вердикт AI для более сложных, неоднозначных случаев (доступно на Pro и Business), а на этих планах можно отправлять пачкой до двадцати текстов в одном запросе вместо вызова на каждый по отдельности.
`POST /users/check` проверяет человека, а не сообщение. Он объединяет глобальный блок-лист CAS, собственный датасет Telm, собранный из модерации во множестве сообществ, и возвращает уровень риска (на Pro и Business), чтобы вы решили, сколько трения применить: чистый аккаунт пропустить сразу, рискованный — придержать на проверку. Встроив это в собственный онбординг, вы поймаете известного нарушителя уже на пороге вашего сайта или приложения, а не после того, как он вступил в Telegram-группу.
Оба вызова отвечают на месте: вы отправляете текст или пользователя — оценку получаете прямо в ответе. Ни очереди для опроса, ни колбэка, которого нужно ждать: решение приходит вместе с ответом.
4Push в тот самый миг, когда это случилось
Опрашивать журнал хорошо для архивирования, но когда нужно *отреагировать* на что-то в момент, когда оно происходит, лучше получать push, а не спрашивать. Вебхуки (на Pro и Business) делают именно это: вы регистрируете эндпоинт, и Telm шлёт на него HTTP-запрос в момент, когда срабатывает нужное событие. События покрывают то, что важно: `spam.detected` и `message.suspicious` для контента и `user.banned`, `user.kicked`, `user.muted`, `user.joined` и `user.left` для состава участников.
Очевидное применение — превратить волну спама в оповещение. Направьте `spam.detected` в ваш мониторинг или систему дежурств, и внезапный всплеск станет вызовом дежурному — там же, где приземляются остальные инциденты; никому не нужно смотреть в Telegram, чтобы заметить начало атаки. Тот же поток питает дашборды в реальном времени, держит внешнюю систему в синхроне с банами или запускает любой ваш процесс.
Поскольку эти запросы приходят из внешнего мира в вашу инфраструктуру, каждая доставка подписана. Каждый запрос несёт заголовок `X-Telm-Signature` вида `v1=hex(hmac_sha256(secret, "timestamp.body"))` — HMAC-SHA256 от метки времени и сырого тела, с ключом-секретом, известным только вам и Telm. Пересчитав эту подпись у себя, вы доказываете, что запрос действительно пришёл от Telm и не был подделан или изменён в пути; метка времени позволяет отклонять устаревшие повторы. Проверяйте подпись до того, как довериться полезной нагрузке, — это несколько строк кода и самый важный шаг безопасного приёмника вебхуков.
5Доставка, на которую можно положиться
Push-модель заслуживает доверия только если справляется с моментами, когда ваш эндпоинт тормозит, перезапускается или ненадолго падает, — и модель Telm справляется. Доставка идёт по принципу «как минимум один раз»: у каждого события есть стабильный `id`, и Telm повторяет попытки, пока эндпоинт не подтвердит приём. Раз «как минимум один раз» означает, что одно и то же событие законно может прийти дважды, дедуплицируйте по этому `id` — записывайте уже обработанные и игнорируйте повторы, — и ваша обработка останется верной, сколько бы раз доставку ни повторяли.
Повторы идут по расширяющемуся расписанию, а не долбят и без того страдающий эндпоинт: сразу, затем через одну минуту, пять минут, тридцать минут, два часа и шесть часов — всего шесть попыток, разнесённых так, чтобы дать восстанавливающемуся сервису шанс вернуться. Если эндпоинт остаётся сломанным — двадцать сбоев подряд и семьдесят два часа без единой успешной доставки, — Telm автоматически прекращает слать на него и уведомляет вас в Telegram, так что мёртвый URL становится ясным сигналом починить приёмник, а не тихо копящейся лавиной сбоев.
Чтобы отладить новую интеграцию, не нужно провоцировать реальные события. Тестовый пинг позволяет по запросу выстрелить пробной доставкой в ваш эндпоинт и убедиться, что проверка подписи и обработчик работают, а история доставок показывает, что было отправлено и чем закончилась каждая попытка, — так что капризный приёмник можно отлаживать по записи, а не гадать.
6Запрашиваемая летопись каждого решения
Всё, что решает движок, записывается, и `GET journal` отдаёт эту запись вашему коду. Каждая строка — одно решение: вердикт, стоящая за ним оценка, сработавшие правила и последовавшее действие. Благодаря курсорной пагинации всю историю можно надёжно пройти — страница за страницей, без пропусков и дублей — и перелить туда, где вы храните записи.
Это делает журнал опорой архива для комплаенса. Команды, которым нужно показать, почему участник был удалён — ради политики платформы, договора с клиентом или регулятора, — по расписанию выгружают журнал в собственное долговременное хранилище, получая независимую, запрашиваемую летопись каждого действия по принуждению, не зависящую от прокрутки Telegram назад. Это те же свидетельства, что журнал модерации в дашборде показывает людям, — теперь доступные вашим системам.
Рядом эндпоинт аналитики возвращает ряды по дням — объёмы и тренды во времени, — так что нагрузку модерации можно строить графиками в собственных BI-инструментах рядом со всем, что вы отслеживаете, а не считывать с экрана. И журнал, и аналитика входят в планы Pro и Business.
7Управление множеством групп из кода
API не только читает и слушает — он ещё и пишет. На Pro и Business можно делать `PATCH` настроек группы и полный набор create/read/update/delete над её правилами и белым списком — всё программно. Всё, что вы настраивали бы руками в дашборде, можно настроить из скрипта.
Именно это делает модерацию в больших масштабах практичной. Агентство или крупный оператор, ведущий десятки сообществ, не хочет открывать каждое и прокликивать одни и те же изменения; он хочет задать политику один раз и применить её везде. С API вы раскатываете новое правило, правите порог или добавляете адрес в каждый белый список по всему парку одним автоматизированным проходом и держите группы в едином строю по мере того, как ваши стандарты меняются.
Ещё это позволяет политике модерации жить в вашей собственной системе контроля версий. Держите желаемую конфигурацию как код, применяйте её через API — и каждое изменение того, как управляются ваши группы, проходит ревью и версионируется, как остальная инфраструктура, а не остаётся попыткой вспомнить, какие настройки вы переключили в каком чате.
8Что входит в каждый план
Граница проста. Проверка текста на спам доступна на любом плане, так что даже бесплатный уровень может использовать детекцию Telm как фильтр в своём продукте. Полная поверхность — проверка пользователей с уровнями риска, журнал решений и аналитика, управление настройками и правилами, а также вебхуки — входит в планы Pro и Business.
У каждого плана есть дневная квота запросов, рассчитанная так, чтобы более тяжёлые интеграции жили на более старших планах:
- **Free** — 100 запросов к API в день, только проверка спама.
- **Basic** — 1 000 запросов к API в день, только проверка спама.
- **Pro** — 10 000 запросов к API в день плюс полная поверхность API и вебхуки.
- **Business** — 50 000 запросов к API в день плюс полная поверхность API и вебхуки.
- Создайте ключи в разделе «Настройки → API и вебхуки», держите их в хранилище секретов, проверяйте подпись каждого вебхука — и тот же движок, что охраняет ваши группы, станет частью вашего собственного стека.