REST API — 自分のコードから Telm を自動化する

1API でできること

Telm REST API を使うと、自分のコードからダッシュボードと同じことができます：任意のテキストをアンチスパムのパイプラインにかける、参加を許可する前に Telegram ユーザーを照会する、グループの保護設定を読み書きする、カスタムルールとホワイトリストを管理する、モデレーションジャーナルと分析データを取得する、リアルタイムのイベント用にウェブフックを登録する。

これにより Telm は、グループの中にいるボットから、どこにでも組み込めるインフラへと変わります — ウェブサイトの登録フォーム、CRM のボット、自作の Telegram ボット、100 のグループを一度に設定するスクリプトなど。

• ベース URL：api.telm.com/api/public/v1 — 安定したバージョン付きのパスです（v1 は契約のバージョンを表します）。
• すべてのリクエストとレスポンスは HTTPS 上の JSON です。
• インタラクティブなドキュメントと機械可読な OpenAPI 3.1 仕様は開発者向けページにあります — 仕様を Postman、コードジェネレーター、AI エージェントに読み込ませれば、数分で連携のひな形を作れます。
• 計測対象の呼び出しでは、すべてのレスポンスに X-Quota-Limit、X-Quota-Used、X-Quota-Reset ヘッダーが返ります。

2リクエストが Telm 内をどう流れるか

公開 API はダッシュボードとは別の、専用のパス接頭辞 /api/public/ にあります。各呼び出しはブラウザのセッションではなく API キーで認証され、プランと利用枠に照らしてチェックされ、グループをモデレーションしているのと同じ本番のエンジンで処理されて、JSON で返されます。

API はボットと同じエンジンとデータにアクセスするので、ダッシュボードで見たり変更したりできることはすべてコードからも行え、コードで行った変更はすぐにダッシュボードに反映されます。

• リクエストはステートレスです：各リクエストが自分のキーを持ち、それ単体で完結します。
• キーはあなたのアカウントを代理して動作し、あなたのアカウントが管理者であるグループにしか触れられません。
• スパムチェックのエンドポイントは本番とまったく同じルールのパイプラインにアクセスするので、API の判定はボットがグループで行う判断と一致します。

3API キーによる認証

すべてのリクエストは、ダッシュボードのログインではなく、tk_live_ にランダムな文字が続く形式の API キーで認証されます。キーはアカウントで作成し、Authorization ヘッダーで Bearer トークンとして、または X-API-Key ヘッダーで送ります。

完全な秘密は作成時に一度だけ表示されます。その後、ダッシュボードはキーを短い接頭辞だけで一覧表示するので、完全な値を保存しなくても識別できます。キーが漏れた場合は取り消して新しいキーを発行してください — 取り消しはすぐに反映されます。

• キーは Authorization: Bearer tk_live_your_key_here として送ります（X-API-Key ヘッダーでも動作します）。
• キーには読み取りまたは書き込みのスコープがあります — GET リクエストには読み取り、データを変更するものには書き込みが必要です。読み取り専用のキーでは作成も編集もできません。
• 有効なキーは同時に最大 10 個まで持てるので、スクリプトやサービスごとに別のキーを使えます。
• キーがない、または無効な場合は 401 が、必要なスコープのないキーでは 403 insufficient_scope が返ります。

4利用できるエンドポイント

API は、スパムチェックとユーザーチェック、グループ管理、アカウントのセルフサービスを中心に構成されています。単一のスパムチェックのエンドポイントはすべてのプランで使え、それ以外は Pro と Business で利用できます。

• POST /spam/check — 1 つのテキストを、本番のトラフィックをモデレーションしているのと同じルールエンジンにかけます（すべてのプラン）。Pro 以上ではオプションで AI チェックを有効にできます。
• POST /spam/check-batch — 1 回の呼び出しで最大 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 ボディを送ると、レスポンスで判定、数値スコア、信頼度、自分のプロダクトで適用できる推奨アクションが返ります。

1 件のテキストは最大 10,000 文字です。Pro 以上では、判断の難しいケース向けに AI チェックを選択でき、こちらは別枠の 1 日の AI チェック枠から消費されます。大量に処理する場合は、バッチのエンドポイントで 1 回の呼び出しに最大 20 件のテキストをチェックでき、利用枠は 1 件ごとにカウントされます。

• 判定とスコアをもとに自分のプロダクトでの対応を決めましょう — フォームの送信をブロックする、リードにフラグを付ける、自作のボットでメッセージを自動削除するなど。
• バッチのエンドポイントはルールのみで、AI の段階は単一テキストのエンドポイントでのみ利用できます。
• リクエストボディには上限があり（単一チェックで約 64 KB、バッチで 256 KB）、超えると 413 が返ります。

6プラン、レート制限、1 日の利用枠

アクセスは 2 つの方法で計測されます：1 分あたりのレート制限（瞬間的な上限）と、UTC の午前 0 時にリセットされる 1 日の呼び出し枠です。どちらもアカウント単位で集計され、すべての API キーで共有されます。単一のスパムチェックのエンドポイントはどのプランでも試せますが、ルール、設定、バッチチェック、ウェブフックを扱う本格的な連携には Pro 以上が必要です。

• Free — 1 日 100 回、スパムチェックのみ。
• Pro — 1 日 10,000 回、API 全体とウェブフック、さらに 1 日 1,000 回の AI チェック。
• Business — 1 日 50,000 回、API 全体とウェブフック、さらに 1 日 10,000 回の AI チェック。
• 1 分あたりのレート制限もプランに応じて上がります — Free は 1 分 60 リクエスト、Pro は 600、Business は 1,800。
• GET /usage と GET /me は利用枠にカウントされないので、いつでも残りの枠を確認できます。

7エラー処理とステータスコード

API は標準の HTTP ステータスコードを使い、ボディに機械可読なエラーコードを含めます。やみくもに再試行するのではなく、これらのコードを読み取って待機したり、アップグレードを促したりするようにクライアントを作りましょう。

1 日の利用枠を超えると、計測対象の呼び出しは daily_quota_exceeded コード、Retry-After ヘッダー、そしてプラン、上限、使用数、リセット時刻、アップグレードの案内を含むボディとともに 429 を返します。上位プランが必要なエンドポイントは、必要なプランとともに 403 plan_required を返します。

• 401 — API キーがない、または無効。
• 403 plan_required — そのエンドポイントには Pro 以上が必要。
• 403 insufficient_scope — 変更を伴う呼び出しに必要な書き込みスコープがキーにない。
• 429 daily_quota_exceeded または rate_limit_exceeded — リセット時刻まで待つかアップグレードする。Retry-After ヘッダーに従ってください。
• 上限に達する前に、X-Quota-* のレスポンスヘッダーを確認しましょう。

8堅牢な連携のためのベストプラクティス

いくつかの習慣で、連携が成長しても信頼性と安全性を保てます。

• キーはクライアント側のコードや git リポジトリではなくシークレットマネージャーに保管し、サービスごとに別のキーを使って、ほかを壊さずに 1 つだけ取り消せるようにしましょう。
• X-Quota-Used と X-Quota-Limit のヘッダーを確認し（または GET /usage をポーリングし）、上限に達した後ではなく、達する前に呼び出しを抑えましょう。
• 429 では Retry-After に従って待機し、403 plan_required では再試行せずにアップグレードの案内を表示しましょう。
• リアルタイムで反応するには、ポーリングよりウェブフックを選び、Telm からイベントを送ってもらいましょう。
• キーは定期的にローテーションし、漏れた可能性があればすぐに交換しましょう。

9よくある連携シナリオ

API は Telegram のメッセージのモデレーション以外にも、さまざまな用途に使われています。

• ウェブサイトやアプリの登録：登録やコメントを受け付ける前に、送信されたテキストやユーザー名を POST /spam/check にかけます。
• 自作の Telegram ボット：ハンドラーからチェックのエンドポイントを呼び出すことで、Telm が管理していないボットでも Telm の判断力を再利用できます。
• 一括設定：設定とルールのエンドポイントを使い、同じルール、ホワイトリスト、設定を何十ものグループにスクリプトで適用します。
• データとアラート：ウェブフックを登録して、モデレーションイベントをデータウェアハウス、ダッシュボード、アラート用のチャンネルにリアルタイムで流します。