1スタックのほかの部分と会話するモデレーション
Telegramの中だけで完結するモデレーションボットは便利ですが、同時に孤島でもあります。それが下す判定——削除したすべてのメッセージ、スクリーニングしたすべてのユーザー、押し返したすべてのレイド——は、誰かがTelegramを開いて見にいかないかぎり、チャットウィンドウの中に閉じ込められたままです。単一のコミュニティならそれで十分。しかし、より大きな運用の一部としてモデレーションを回すチームにとっては、あなたの空間を誰が荒らしているかを最もよく知っているシステムが、ほかに動かしているどのシステムとも会話できない、ということを意味します。
公開REST APIとウェブフックが、その隙間を埋めます。これらはTelmを、自己完結型のボットから、すでに手元にあるツールに組み込めるコンポーネントへと変えます——監視・オンコール体制、コンプライアンス用アーカイブ、自社プロダクト、社内ダッシュボードへ。グループを守るのと同じエンジンが、ほかのシステムから問い合わせ、購読し、駆動できるものになります。
本ガイドでは、APIとウェブフックが実際に何を公開するのか——エンドポイント、イベント、セキュリティモデル——と、チームがそれらで具体的に何を作るのかを解説します。以下はすべて、今日利用できる本物の機能です。待つべきSDKもなく、プロダクトが計画中にとどまっているだけの記述もここにはありません。
2REST APIと、あなたのキー
APIは `https://api.telm.com/api/public/v1` にあります。ふつうのREST インターフェースで——通常のHTTPSリクエストとJSONで、どんな言語からでも、専用のクライアントライブラリなしに呼び出せます。コードがHTTPリクエストを送れるなら、Telmと会話できます。
認証はAPIキーで行います。キーはダッシュボードの Settings → API & Webhooks で作成し、それぞれ作成時にちょうど一度だけ表示されます——その場でシークレットストアにコピーしてください。あとから取り戻すことはできません。キーには `tk_live_` の接頭辞が付くので、ログや設定の中で見分けやすくなっています。各キーはスコープ——readまたはwrite——を持つので、判定ログを取得するだけのサービスはread-onlyキーを、設定を変更する自動化はwriteキーを持てます。システムごとに1つずつキーを発行しておけば、漏えいしたキーや引退させたキーを失効させても、ほかに影響しません。
利用はプランに紐づく日次リクエストクォータで制御されるため、スループットは予測可能で、暴走したスクリプト1つがすべてを使い尽くすこともありません。最も軽いチェック——テキストのスパムスキャン——はそのクォータの範囲内で全プランで利用でき、より広い機能面——判定ジャーナルから設定管理、ウェブフックまで——はProとBusinessプランの一部です。正確な数値は末尾にまとめてあります。
3テキストとユーザーをオンデマンドでスクリーニング
2つのエンドポイントで、Telegramグループを一度もメッセージが通らないまま、自分のコードからTelmの判断をオンデマンドで走らせられます。
`POST /spam/check` は、あなたのコミュニティを守っているのとまったく同じ本番エンジン——共有のスパマーシグナル、パターンルール、分類器——にテキストを通し、判定を返します。これは全プランで使える唯一の呼び出しであり、自社プロダクトにとって自然なスパムフィルターになります——コメント、登録時のプロフィール、サポートチケット、マーケットプレイスの出品を、Telegram空間を守るのと同じ検出でスクリーニングできます。より難しく曖昧なケースにAI判定を加えるには `include_ai` を付け（ProとBusinessで利用可能）、それらのプランでは1件ずつ呼ぶ代わりに1リクエストで最大20件のテキストをバッチ処理できます。
`POST /users/check` は、メッセージではなく人物をスクリーニングします。グローバルなCASブロックリストと、多数のコミュニティのモデレーションから構築されたTelm独自のデータセットを組み合わせ、リスクレベル（ProとBusinessで）を返すので、どれだけの摩擦をかけるか判断できます——クリーンなアカウントはそのまま通し、リスクのあるアカウントはレビュー用に保留する。これを自社のオンボーディングに組み込めば、既知の悪質な行為者を、Telegramグループに参加したあとではなく、ウェブサイトやアプリの入り口で捕まえられます。
どちらの呼び出しもインラインで応答します——テキストやユーザーを送れば、その評価がレスポンスで返ってきます。ポーリングすべきキューも、待つべきコールバックもありません——判定は返信とともに届きます。
4起きたその瞬間にプッシュされる
ジャーナルのポーリングはアーカイブには十分ですが、何かが起きた瞬間に*反応*したいときは、尋ねるのではなくプッシュされたいものです。ウェブフック（ProとBusinessで）はまさにそれを行います——エンドポイントを登録すると、Telmは関連するイベントが発火した瞬間にHTTPリクエストを送ります。イベントは重要な瞬間をカバーします——コンテンツ向けの `spam.detected` と `message.suspicious`、メンバーシップ向けの `user.banned`、`user.kicked`、`user.muted`、`user.joined`、`user.left`。
分かりやすい使い道は、スパムの波をアラートに変えることです。`spam.detected` を監視やオンコールのシステムに向けておけば、急な急増が当番の担当者へのページ通知になります——ほかのインシデントが届くのと同じ場所に。誰かがTelegramを見張っていなくても、攻撃の始まりに気づけます。同じストリームはリアルタイムのダッシュボードに供給したり、外部システムをBANと同期させ続けたり、好きなワークフローを起動したりできます。
これらのリクエストは外の世界からあなたのインフラへ入ってくるため、すべての配信に署名が付きます。各リクエストは `X-Telm-Signature` ヘッダーを、`v1=hex(hmac_sha256(secret, "timestamp.body"))` の形で運びます——タイムスタンプと生の本文にかけた、あなたとTelmだけが共有するシークレットを鍵とするHMAC-SHA256です。自分側でその署名を再計算すれば、リクエストが本当にTelmから来たもので、途中で偽造も改ざんもされていないことが証明できます。タイムスタンプによって古いリプレイを拒否できます。ペイロードを信頼する前に署名を検証してください——数行のコードで済み、安全なウェブフック受信側で最も重要な一手です。
5頼れる配信
プッシュ型が信頼できるのは、エンドポイントが遅い・再起動中・一時的に落ちているときにも対処できる場合だけです——Telmのそれは対処します。配信は少なくとも1回：すべてのイベントは安定した `id` を持ち、Telmはエンドポイントが受領を確認するまで試み続けます。少なくとも1回は同じイベントが正当に2回届きうることを意味するので、その `id` で重複排除してください——処理済みのものを記録し、繰り返しは無視する——そうすれば配信が何度リトライされても、処理は正しいままです。
リトライは、苦しんでいるエンドポイントを叩き続けるのではなく、段階的に広がるスケジュールに従います——即時、続いて1分後、5分後、30分後、2時間後、6時間後——全部で6回の試行を、回復しつつあるサービスに戻ってくる余地を与えるよう間隔を空けて行います。エンドポイントが壊れたまま——連続20回の失敗と、成功のない72時間——になると、Telmは自動的に送信を止め、Telegramで通知します。こうして、死んだURLは、失敗が静かに積み上がる無音の放水ではなく、受信側を直すべきという明確な合図になります。
新しい連携を正しく仕上げるのに、テストのために実イベントを引き起こす必要はありません。テストpingを使えば、サンプル配信をオンデマンドでエンドポイントに撃ち込み、署名チェックとハンドラーが動くことを確認できます。そして配信履歴は、何が送られ、各試行がどうなったかを示すので、当て推量ではなく記録から、挙動のおかしい受信側をデバッグできます。
6すべての判定を、問い合わせ可能な記録に
エンジンが決めることはすべて記録され、`GET journal` がその記録をあなたのコードに渡します。各エントリは1つの判定です——判定結果、その背後にあるスコア、発火したルール、そしてそれに続いたアクション。カーソルページネーションなので、履歴全体を確実にたどれます——ページごとに、欠落も重複もなく——そして記録を保管する場所へ取り込めます。
これによってジャーナルはコンプライアンス用アーカイブの背骨になります。メンバーがなぜ排除されたのかを示さなければならないチーム——プラットフォームのポリシー、クライアント契約、あるいは規制当局のために——は、ログを自分たちの長期保管先へ定期的にエクスポートし、Telegramをさかのぼってスクロールすることに依存しない、独立して問い合わせ可能なすべての執行アクションの記録を手にします。これはダッシュボードの監査ログが人に見せるのと同じ証跡を、あなたのシステム向けに提供するものです。
その傍らで、分析エンドポイントは日ごとの系列——時間の経過にともなう量と傾向——を返すので、追跡しているほかのすべてと並べて、自分のBIツールでモデレーション負荷をグラフ化できます。画面から読み取るのではありません。ジャーナルと分析はどちらもProとBusinessプランの一部です。
7多数のグループをコードから管理する
APIは読み取りと購読だけではありません——書き込みもします。ProとBusinessでは、グループの設定を `PATCH` し、そのルールとホワイトリストに対して完全な作成・読み取り・更新・削除をすべてプログラムから実行できます。ダッシュボードで手作業で設定するものは、何であれスクリプトから設定できます。
これこそが、大規模なモデレーションを実務的にするものです。数十のコミュニティを管理する代理店や大規模運営者は、一つひとつを開いて同じ変更をクリックして回りたくはありません——ポリシーを一度定義し、それをどこにでも適用したいのです。APIを使えば、新しいルールの展開、しきい値の調整、あるいは全グループ群のすべてのホワイトリストへのアドレス追加を、1回の自動化されたパスで行え、基準の進化に合わせてグループを歩調をそろえたまま保てます。
さらに、モデレーションポリシーを自分のソース管理の中で生かすこともできます。望ましい設定をコードとして保持し、APIを通じて適用すれば、グループの統治のされ方に対するすべての変更が、インフラのほかの部分と同じようにレビューされ、バージョン管理されます——どのチャットでどの設定を切り替えたかを覚えておくのとは、天と地の差です。
8各プランに含まれるもの
境界線はシンプルです。テキストのスパムチェックは全プランで使えるので、無料枠でさえTelmの検出を自社プロダクトのフィルターとして利用できます。より広い機能面——リスクレベル付きのユーザースクリーニング、判定ジャーナルと分析、設定とルールの管理、そしてウェブフック——はProとBusinessプランの一部です。
すべてのプランに日次リクエストクォータが付き、重い連携ほど重いプランに乗るようサイズ調整されています：
- **Free** — 1日100 APIリクエスト、スパムチェックのみ。
- **Basic** — 1日1,000 APIリクエスト、スパムチェックのみ。
- **Pro** — 1日10,000 APIリクエスト、加えてフルAPI機能面とウェブフック。
- **Business** — 1日50,000 APIリクエスト、加えてフルAPI機能面とウェブフック。
- キーは Settings → API & Webhooks で作成し、シークレットストアに保管し、すべてのウェブフックの署名を検証しましょう——そうすれば、あなたのグループを守るのと同じエンジンが、あなた自身のスタックの一部になります。