1Модерація, що розмовляє з рештою вашого стека
Бот модерації, який живе цілком усередині Telegram, корисний, але водночас це острів. Рішення, які він ухвалює, — кожне видалене повідомлення, кожен перевірений користувач, кожен відбитий рейд — лишаються замкненими у вікні чату, доки хтось не відкриє Telegram, щоб подивитися. Для однієї спільноти це нормально. Для команди, яка веде модерацію як частину більшої операції, це означає, що одна система, яка знає найбільше про те, хто зловживає вашими просторами, — це та сама система, яка не може розмовляти ні з чим іншим, що ви запускаєте.
Публічний REST API та webhooks закривають цю прогалину. Вони перетворюють Telm із самодостатнього бота на компонент, який можна вбудувати в інструменти, що у вас уже є: ваш моніторинг і on-call, ваш архів для комплаєнсу, ваш власний продукт, ваші внутрішні дашборди. Той самий движок, що захищає ваші групи, стає чимось, що ваші інші системи можуть запитувати, слухати й керувати ним.
Цей гайд проходить крізь те, що API та webhooks насправді відкривають — ендпоінти, події, модель безпеки — і конкретні речі, які команди на них будують. Усе нижче — це реальна можливість, доступна вже сьогодні; немає SDK, на який треба чекати, і нічого з описаного тут продукт не «лише планує зробити».
2REST API та ваші ключі
API живе за адресою `https://api.telm.com/api/public/v1`. Це звичайний REST-інтерфейс — ви звертаєтеся до нього простими HTTPS-запитами та JSON, будь-якою мовою, без спеціальної клієнтської бібліотеки. Якщо ваш код уміє зробити HTTP-запит, він уміє розмовляти з Telm.
Автентифікація — за API-ключем. Ключі ви створюєте в кабінеті в розділі Settings → API & Webhooks, і кожен показується вам рівно один раз під час створення — скопіюйте його у своє сховище секретів тут і зараз, бо потім його вже не отримати. Ключі мають префікс `tk_live_`, тож їх легко впізнати в логах і конфігах. Кожен ключ несе скоуп — читання або запис — тож сервіс, якому треба лише витягувати журнал рішень, може тримати ключ read-only, а автоматизація, що змінює налаштування, отримує ключ на запис. Робіть по одному ключу на систему, і відкликання злитого чи виведеного з ужитку ключа ніколи не зачепить інші.
Використання регулюється щоденною квотою запитів, прив'язаною до вашого плану, тож пропускна здатність передбачувана й один розігнаний скрипт не вичерпає все. Найлегша перевірка — сканування тексту на спам — доступна на кожному плані в межах цієї квоти; повніша поверхня, від журналу рішень до керування налаштуваннями та webhooks, — частина планів Pro та Business. Точні цифри розкладені в кінці.
3Перевірка текстів і користувачів на вимогу
Два ендпоінти дають запускати судження Telm на вимогу, з вашого власного коду, без того щоб повідомлення бодай раз пройшло через групу Telegram.
`POST /spam/check` надсилає шматок тексту через точно той самий бойовий движок, що охороняє ваші спільноти, — спільні сигнали про спамерів, правила-патерни, класифікатори — і повертає вердикт. Це той єдиний виклик, доступний на кожному плані, що робить його природним спам-фільтром для вашого власного продукту: перевіряйте коментарі, біографії при реєстрації, тікети підтримки чи оголошення маркетплейсу тією самою детекцією, що захищає ваші простори в Telegram. Додайте `include_ai`, щоб докласти AI-вердикт для складніших, неоднозначніших випадків (доступно на Pro та Business), а на цих планах ви можете пакетувати до двадцяти текстів в одному запиті замість викликати по разу на елемент.
`POST /users/check` перевіряє людину, а не повідомлення. Він поєднує глобальний блоклист CAS, власний датасет Telm, зібраний із модерації в багатьох спільнотах, і повертає рівень ризику (на Pro та Business), тож ви можете вирішити, скільки тертя докласти — пропустити чистий акаунт наскрізь, притримати ризиковий на перегляд. Вбудувавши це у власний онбординг, ви ловите відомого зловмисника вже на порозі вашого сайту чи застосунку, а не лише після того, як він приєднався до групи Telegram.
Обидва виклики відповідають вбудовано: ви надсилаєте текст чи користувача, ви отримуєте оцінку назад у відповіді. Немає черги, яку треба опитувати, і немає колбека, на який треба чекати, — рішення приходить разом із відповіддю.
4Push тієї миті, коли це стається
Опитувати журнал добре для архівування, але коли ви хочете *зреагувати* на щось у мить, коли воно стається, вам потрібно, щоб вам штовхнули, а не питати самому. Webhooks (на Pro та Business) роблять саме це: ви реєструєте ендпоінт, і Telm надсилає йому HTTP-запит тієї миті, коли спрацьовує релевантна подія. Події покривають моменти, що мають значення, — `spam.detected` та `message.suspicious` для контенту, а також `user.banned`, `user.kicked`, `user.muted`, `user.joined` та `user.left` для членства.
Очевидне застосування — перетворити хвилю спаму на алерт. Наведіть `spam.detected` на ваш моніторинг чи on-call — і раптовий сплеск стає пейджем тому, хто на чергуванні, у тому самому місці, куди приземляються інші ваші інциденти; нікому не треба стежити за Telegram, щоб помітити початок атаки. Той самий потік живить дашборди в реальному часі, тримає зовнішню систему синхронізованою з банами чи запускає будь-який робочий процес, який захочете.
Оскільки ці запити приходять із зовнішнього світу у вашу інфраструктуру, кожна доставка підписана. Кожен запит несе заголовок `X-Telm-Signature` у формі `v1=hex(hmac_sha256(secret, "timestamp.body"))` — HMAC-SHA256 від часової позначки й сирого тіла, з ключем-секретом, який знаєте лише ви й Telm. Перерахунок цього підпису на вашому боці доводить, що запит справді прийшов від Telm і не був підроблений чи змінений у дорозі; часова позначка дає відкинути застарілі повтори. Перевіряйте підпис, перш ніж довіряти payload, — це кілька рядків коду й найважливіший крок у безпечному приймачі webhook.
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 як фільтр у власному продукті. Повна поверхня — перевірка користувачів із рівнями ризику, журнал рішень та аналітика, керування налаштуваннями й правилами та webhooks — частина планів Pro та Business.
Кожен план отримує щоденну квоту запитів, розміром так, щоб важчі інтеграції сиділи на важчих планах:
- **Free** — 100 API-запитів на день, лише перевірка спаму.
- **Basic** — 1 000 API-запитів на день, лише перевірка спаму.
- **Pro** — 10 000 API-запитів на день, плюс повна поверхня API та webhooks.
- **Business** — 50 000 API-запитів на день, плюс повна поверхня API та webhooks.
- Створіть ключі в розділі Settings → API & Webhooks, тримайте їх у сховищі секретів, перевіряйте підпис кожного webhook — і той самий движок, що охороняє ваші групи, стає частиною вашого власного стека.