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で通常のTelegramアカウントを接続する場合は、API IDとAPI hashを用意してTelegram認証ガイドに従ってください。このフローに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のユーザーアカウント接続 | コードまたはQR認証用のAPI ID + API hash | 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の公式手順は短いものですが、ページ名を正しく確認する必要があります。
- 公式Telegramアプリに有効な電話番号を登録し、その番号を維持します。
- my.telegram.org を開き、
/authでアカウントにログインします。 - API development tools を選びます。
- アプリケーションフォームに入力します。
- 発行された
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": "telegram",
"auth_mode": "code",
"provider_data": {
"api_id": 12345678,
"api_hash": "0123456789abcdef0123456789abcdef",
"phone": "+886912345678"
}
}QR認証でも provider_data.api_id と provider_data.api_hash は必要で、アカウント所有者がTelegramで有効期間の短いQRを承認します。Telegram認証APIリファレンスには、コード、QR、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 の両方が含まれます。QRはユーザーが承認する手順であり、アプリケーション認証情報の代わりではありません。
UnifyPortはBotFather tokenでTelegramを接続できるか
通常のTelegramアカウント認証フローでは接続できません。コードモードとQRモードでは provider_data.api_id と provider_data.api_hash を使用し、コードモードではアカウントの電話番号も使用します。Botとして運用したい場合は、公式Bot APIを直接使用してください。
次のステップ
既存のTelegramアカウントを接続する場合は、Telegram認証ガイドを開き、コードまたはQRフローを選択してください。Botだけが必要なら、@BotFather と公式Bot APIを使用します。
出典
- Telegram：Telegram Applicationの作成
- Telegram：BotFatherから「Hello World」まで
- Telegram：ユーザー認証
- Telegram：QRコードでログイン
出典および製品ドキュメントは2026-07-19に確認済みです。