Telegram API ID・API HashとBot Tokenの違い：必要な認証情報は？

Telegramのbot tokenは、1つのBotをHTTP Bot APIに対して認証するものであり、個人のTelegramアカウントにログインするものではありません。API IDとAPI hashはクライアントアプリケーションを識別し、コードやQRログインを含め、TelegramのMTProto API経由でユーザーアカウントを認証するときに必要です。操作したいアカウントの種類に応じて認証情報を選びます。Botとして動作する → bot token、既存のユーザーアカウントとして動作する → API IDとAPI hashです。

要点

• 別個のTelegram Botとして動作する連携には、@BotFather から取得した bot token を使います。
• 既存のTelegramユーザーアカウントを認証する独自クライアントを開発する場合は、my.telegram.org で API IDとAPI hash を取得します。
• Bot tokenをAPI ID/API hashの代わりにはできません。QRコードをスキャンする場合もアプリケーションの認証情報は必要です。
• Bot token、API hash、ログインコード、認証済みセッションの情報をソース管理やログに残さないでください。
• UnifyPortでは、アプリケーション認証情報の2項目を両方省略してプラットフォームのデフォルト値を使うか、自分の認証情報の組を指定できます。このアカウント認証フローにBotFather tokenを入力してはいけません。

Telegram API ID・API hashとbot tokenの違い

3つともTelegramへの何らかのアクセスを許可するため、名前を混同しやすいものです。しかし、属するAPI領域も認証の対象も異なります。

構築するもの	認証情報	取得元	認証後に操作するアカウント
HTTP Bot API連携	Bot token	@BotFather	別個のBotアカウント
Telegramユーザーとしてログインするクライアント	API ID + API hashと、コード、QR、またはその他サポートされているユーザーログイン手順	my.telegram.org → API development tools	認証されたユーザーアカウント
UnifyPortのユーザーアカウント接続	プラットフォームのデフォルト認証情報または独自のAPI ID + API hashと、コードまたはQRによる承認	デフォルト値はUnifyPortが提供。独自の認証情報は my.telegram.org で取得	ログインを承認したTelegramアカウント

Telegram公式のBotチュートリアルでは、bot tokenが認証するのは Botであり、あなたのアカウントではない と明記されています。このtokenは https://api.telegram.org/bot<TOKEN>/getMe などのエンドポイントへ送信され、@BotFather で取り消すこともできます。

一方、API IDとAPI hashはTelegramのクライアントアプリケーションに属します。my.telegram.org にログインし、API development tools のフォームを入力するとTelegramから発行されます。ユーザー認証では、これらのアプリケーション認証情報と、ユーザー自身が行うログイン手順を組み合わせます。たとえば、auth.sendCode は電話番号、api_id、api_hash を受け取り、認証に成功すると生成されたクライアントセッションがそのユーザーに紐づきます。

ここが決定的な違いです。bot tokenは操作するBotを決め、API ID/API hashはユーザーアカウントのログインに参加するクライアントを識別します。

どの認証情報を選ぶべきか

まず、どのアカウントとしてメッセージを送受信する必要があるかを確認します。

Botとしての運用で要件を満たせる場合はbot tokenを選ぶ

ユーザーがBotのusernameに意図的に話しかける、Botをグループに追加する、またはBot固有の機能を使う場合は、公式Bot APIを使用します。@BotFather でBotを作成し、そのtokenをパスワードと同様に保管して、ポーリングまたはTelegram WebhookでBot APIの更新を受け取ります。

Botを中心に設計されたTelegram専用製品では、通常これが最もシンプルな方法です。BotのライフサイクルはTelegramが管理し、APIも公式で、個人ユーザーのセッションを認証する必要がありません。Telegramネイティブのチャット自動化とクロスチャネル受信キューの比較では、この公式モデルが適している場面を詳しく説明しています。

ユーザーアカウントとしての運用が必要な場合はAPI IDとAPI hashを選ぶ

新しいBotアカウントを作るのではなく、既存のTelegramアカウントを認証する必要がある製品では、TelegramのクライアントAPIを使用します。まずアプリケーションがAPI IDとAPI hashで自身を識別し、その後、アカウント所有者が確認コード、QR承認、設定済みの場合は2FAなどのユーザーログイン手順を完了します。

API ID/API hashだけでアカウントにログインできるわけではありません。これらが識別するのはアプリケーションであり、ユーザー自身が行う認証によってアカウントセッションが生成されます。同様に、電話番号やQR画像もアプリケーション認証情報の代わりにはなりません。

既存のTelegramアカウントから別のシステムへメッセージを転送することが最終目的なら、Telegram-to-Slack relayの構築記録で、アカウント接続後の下流Webhookアーキテクチャを確認できます。

my.telegram.orgでAPI IDとAPI hashを取得する方法

Telegramの公式手順は短いものですが、ページ名を正しく確認する必要があります。

1. 公式Telegramアプリに有効な電話番号を登録し、その番号を維持します。
2. my.telegram.org を開き、/auth でアカウントにログインします。
3. API development tools を選びます。
4. アプリケーションフォームに入力します。
5. 発行された api_id と api_hash をサーバー側の認証情報ストアに保存します。

Telegramでは現在、1つの電話番号につき1つのAPI IDが許可されており、クライアントライブラリは不正利用がないか監視されると説明されています。リリースするアプリケーションには自分のアプリケーション認証情報を使用し、Telegram API Terms of Serviceに従ってください。Telegramのオープンソースクライアントに含まれる、用途が限定されたサンプルAPI IDを本番環境へコピーしてはいけません。

QRログインにもAPI IDとAPI hashは必要か

必要です。QRで変わるのは、ユーザーがログインを承認する方法です。どのクライアントアプリケーションがログインを要求しているかは変わりません。

Telegram公式のQRフローは auth.exportLoginToken から始まり、そのパラメーターには api_id と api_hash が含まれます。クライアントは返されたtokenを tg://login QRコードとして表示し、ログイン済みのTelegramアプリでスキャンして承認します。Telegramによると、このlogin tokenは通常約30秒で期限切れになるため、期限切れのQRは更新が必要です。

つまり、「QRかAPI認証情報か」という選択ではありません。ユーザー認証では、QRはアプリケーション認証情報と 組み合わせて 使う承認方法です。

UnifyPortの位置づけ

UnifyPortは通常のTelegramアカウントを非公式インターフェース経由で接続するもので、Telegram Botを作成するものではありません。そのため、コード認証とQR認証のどちらもユーザーアカウント向けの認証情報を使用します。

コード認証では、provider: "telegram"、auth_mode: "code"、provider_data.phone を指定してアカウントを作成します。provider_data.api_id と provider_data.api_hash を両方省略すると、プラットフォームのデフォルト認証情報を使います。独自アプリを使う場合は、同じアプリの2項目を文字列で一緒に指定してください。以下は独自の認証情報を使う例です。使用前にプレースホルダーを置き換えてください。

{
  "provider": "telegram",
  "auth_mode": "code",
  "provider_data": {
    "api_id": "12345678",
    "api_hash": "0123456789abcdef0123456789abcdef",
    "phone": "+886912345678"
  }
}

QR認証では auth_mode: "qrcode" を使います。2項目を両方省略してデフォルト値を使うか、独自アプリの認証情報を文字列の組で指定できます。アカウント所有者によるTelegramでのQR承認は引き続き必要です。Telegram認証APIリファレンスでコード、QR、2FA、セッションの手順を確認できます。デフォルト認証情報はユーザーの承認や2FAを代替しません。

認証後、Telegramの受信メッセージは、接続済みの他のプロバイダーと同じ署名付き message.received イベント として受信できます。この通常アカウントのフローにBotFather tokenを入力することはありません。

制限とトレードオフ

別個のBotアカウントで製品要件を満たせる場合は、Telegram公式のBot APIを使ってください。Bot向けに設計されており、ユーザーアカウントのセッションを維持する必要がありません。

クライアント／ユーザーアカウントフローは、既存アカウントが本当に必要な場合にのみ使用してください。認証すると機密性の高いセッション情報が生成され、アカウントには引き続きTelegramのルールが適用されます。また、APIへアクセスできても、スパムやその他の禁止行為が許可されるわけではありません。UnifyPortはbot tokenをユーザーセッションに変換せず、利用者に代わってAPI IDを作成せず、Telegramのプラットフォーム側の制御を取り除くこともありません。

また、Telegram Login for websitesは、この認証情報の選択とは別のものです。Telegramの現在のウェブログインシステムは独自のクライアント設定を持つOpenID Connectフローであり、Bot API tokenとMTProtoユーザーアカウント認証のどちらの代わりにもなりません。

FAQ

Telegram API IDとbot tokenは同じものか

いいえ。API IDはTelegram API認証に参加するクライアントアプリケーションを識別します。Bot tokenは1つのBotをBot APIに対して認証します。発行元も認証の対象も異なります。

Bot tokenを持っていてもAPI IDとAPI hashは必要か

通常のHTTP Bot API呼び出しには不要です。そのBotのbot tokenを使用します。連携がクライアントAPI経由でTelegramユーザーを認証する場合はAPI IDとAPI hashが必要で、bot tokenではそのユーザーにログインできません。

my.telegram.org/authはどこにあるか

https://my.telegram.org/ を開き、Telegramに登録した電話番号でログインします。認証後に API development tools を選ぶと、その番号に紐づくAPI IDとAPI hashを作成または確認できます。

API hashなしでQRログインは使えるか

Telegramのプロトコルでは、auth.exportLoginToken に api_id と api_hash の両方が必要です。UnifyPortではリクエストの2項目を両方省略でき、その場合はプラットフォームがデフォルト認証情報を提供します。独自アプリでは両方を文字列で指定します。アカウント所有者によるQR承認は引き続き必要です。

UnifyPortはBotFather tokenでTelegramを接続できるか

通常アカウントの認証フローではBotFather tokenを受け付けません。UnifyPortはコード、QR、またはセッション認証でユーザーアカウントを接続します。アプリの認証情報にはデフォルト値または独自の組を使い、コード認証ではアカウントの電話番号も必要です。Botとして動作させる場合は公式Bot APIを使ってください。

次のステップ

既存のTelegramアカウントを接続する場合は、Telegram認証ガイドを開き、コードまたはQRフローを選択してください。Botだけが必要なら、@BotFather と公式Bot APIを使用します。

出典

• Telegram：Telegram Applicationの作成
• Telegram：BotFatherから「Hello World」まで
• Telegram：ユーザー認証
• Telegram：QRコードでログイン

元の記事のプラットフォーム資料は2026-07-19に確認しました。UnifyPortのアプリケーション認証情報の扱いは2026-10-13に再確認しました。