TelegramユーザーアカウントをWebhookに接続する：コード認証・QR認証ガイド

既存のTelegramユーザーアカウントをWebhookに接続するには、まず自分のアプリ用のapi_idとapi_hashを取得し、認証を始める前にWebhookを登録します。その後、UnifyPortでTelegramメッセージングアカウントを作成し、コード認証またはQR認証を完了します。コード認証には電話番号が必要で、2段階認証を求められる場合があります。QR認証でもAPI認証情報は必要ですが、ログイン済みのTelegramアプリからアカウント所有者が承認します。

要点

• ユーザーアカウント認証ではapi_idとapi_hashを使います。BotFatherのbot tokenとは別物です。
• 認証状態と新着メッセージを受け取れるよう、Webhookを先に登録します。
• ログインコードを入力できるならauth_mode: "code"、既存アプリでの承認が便利ならauth_mode: "qrcode"を選びます。
• api_hash、ログインコード、2段階認証パスワード、QR内容、API key、signing_secretは機密情報です。
• 認証後は、署名検証済みで方向がinboundのmessage.receivedだけを処理します。

認証情報の違いから確認したい場合は、先にTelegram API ID/API hashとbot tokenの比較を参照してください。

TelegramユーザーアカウントWebhookの設定手順

構成要素は、Telegramアプリ認証情報、自社管理の受信エンドポイント、UnifyPortのメッセージングアカウント、ユーザー操作が必要な認証の4つです。この境界を分けると、問題が起きた場所を判断しやすくなります。

1. Telegramアプリの認証情報を取得する

Telegramの公式アプリ作成ガイドでは、ユーザー認証にapi_idとapi_hashが必要とされています。my.telegram.orgのAPI development toolsで自分のアプリ用に発行し、hashはシークレット管理基盤に保存してください。リポジトリやログには残しません。

これはBot APIとは異なるIDモデルです。Telegramは公式Bot APIをbot向けのHTTPインターフェースと説明しています。専用bot IDやbotコマンドが目的なら公式Bot APIが適しています。既存ユーザーアカウントを接続する場合や、TelegramをLINEなど他チャネルと同じ入電処理へ流したい場合は、ここで扱う非公式インターフェースが選択肢になります。

サンプルまたは公開済みのアプリIDを引き継いだ場合は、利用前に出所を確認してください。API_ID_PUBLISHED_FLOOD復旧チェックリストでは、不適切な認証情報を安全に差し替える手順を説明しています。

2. ログイン前に署名付きWebhookを登録する

UnifyPortにはメッセージ履歴を読むREST APIや、欠落したpayloadの保証付き再配信はありません。先に受信側を用意し、必要なイベントを到着時に保存します。

curl -X POST https://api.unifyport.ai/v1/webhook-endpoints \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"url\": \"$PUBLIC_WEBHOOK_URL\",
    \"status\": \"active\",
    \"subscribed_events\": [\"message.received\", \"account.auth.required\", \"account.auth.succeeded\", \"account.auth.failed\", \"account.status.updated\"],
    \"signing_secret\": \"$WEBHOOK_SIGNING_SECRET\"
  }"

正確なリクエスト仕様はWebhook endpoint作成にあります。署名を有効にした場合、X-Device-Timestamp、ピリオド、raw request bodyを連結した値のHMAC-SHA256（16進数）がX-Device-Signatureと一致することを確認します。raw body、タイムスタンプ、冪等性、再試行はWebhook HMACとリプレイ対策で詳しく説明しています。

3A. コード認証を使う

アカウント作成時にprovider_data.api_id、provider_data.api_hash、provider_data.phoneを指定します。

curl -X POST https://api.unifyport.ai/v1/accounts \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"name\": \"Telegram Support\",
    \"provider\": \"telegram\",
    \"region\": \"global\",
    \"status\": \"active\",
    \"auth_mode\": \"code\",
    \"capabilities\": [\"send_message\", \"receive_message\"],
    \"provider_data\": {
      \"api_id\": $TELEGRAM_API_ID,
      \"api_hash\": \"$TELEGRAM_API_HASH\",
      \"phone\": \"$TELEGRAM_PHONE\"
    }
  }"

レスポンスのアカウントidを保存し、認証を開始してからTelegramで受け取ったコードを送信します。

curl -X POST "https://api.unifyport.ai/v1/accounts/$ACCOUNT_ID/auth/start" \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

curl -X POST "https://api.unifyport.ai/v1/accounts/$ACCOUNT_ID/auth/code" \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"code\": \"$TELEGRAM_LOGIN_CODE\"}"

Telegramの公式ユーザー認証リファレンスには2段階認証の分岐もあります。UnifyPortの認証状態がawaiting_passwordになった場合に限り、/v1/accounts/{account_id}/auth/passwordへパスワードを送ります。パスワードはログへ出力しないでください。

3B. QR認証を使う

QRの場合はauth_mode: "qrcode"でアカウントを作成し、provider_data.api_idとprovider_data.api_hashを指定します。このモードではphoneフィールドは不要です。

curl -X POST "https://api.unifyport.ai/v1/accounts/$ACCOUNT_ID/auth/qr/start" \
  -H "X-Api-Key: $UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

GET /v1/accounts/{account_id}/authで状態を読むか、POST /v1/accounts/{account_id}/auth/qr/checkで確認します。auth_payload.qr_codeはアカウント所有者だけに表示してください。Telegramの公式QRログイン仕様では、ログイン済みのTelegramアプリでQRを読み取り、承認する必要があります。また期限切れtokenは再生成します。APIが新しいpayloadを返したら、表示中のQRも更新します。

コード、QR、2段階認証、session importの全分岐はTelegram認証API Referenceで確認できます。

4. 認証を確認してメッセージを受信する

account.auth.succeededを受け取ったら、GET /v1/accounts/{account_id}で状態を照合します。認証成功後は通常runtimeが自動起動しますが、準備完了と決めつけず、実際のruntime_statusを確認してください。

Telegramの受信メッセージは標準イベントとして届きます。

{
  "id": "evt_b1a7c3e5f8",
  "type": "message.received",
  "provider": "telegram",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-06-08T12:37:00Z",
  "data": {
    "conversation": { "id": "5005", "type": "user" },
    "sender": { "id": "4004", "type": "user", "name": "Jordan Lee" },
    "message": {
      "id": "3003",
      "text": "Can you check my order?",
      "direction": "inbound",
      "sent_at": "2026-06-08T12:37:00Z"
    },
    "event": { "kind": "message_received" }
  }
}

署名検証後、typeがmessage.receivedで、data.message.directionがinboundのイベントだけをルーティングします。イベントIDで冪等処理し、正当な配信には2xxを返し、ワークフローに必要なフィールドを保存します。

制約と選び方

ユーザーアカウント接続は、すべてのbot用途を置き換えるものではありません。bot ID、botコマンド、Telegramのbot専用インターフェースが必要なら公式Bot APIを選びます。既存ユーザーアカウントが必要な場合、または日本のサポート窓口でTelegramとLINEを同じ署名付き受信キューへ統合したい場合は、UnifyPortの構成が適しています。後からWhatsApp、TikTok、Zalo、Xも同じハンドラーへ追加できます。

UnifyPortは非公式インターフェースであり、上流の挙動や利用可否はアカウントにより異なる場合があります。Telegram API Terms of Serviceと、自社のセキュリティ・プライバシー要件への対応は引き続き必要です。認証情報、QR、session情報は、ログインを行うアカウント所有者以外に公開しないでください。

よくある質問

Telegram bot tokenは必要ですか？

不要です。ユーザーアカウントではapi_idとapi_hashを使います。bot tokenは公式Bot API用です。

QR認証でもAPI IDとAPI hashが必要ですか？

必要です。UnifyPortのQR認証でもprovider_data.api_idとprovider_data.api_hashを指定し、承認方法だけが変わります。

2段階認証を要求されたらどうしますか？

状態がawaiting_passwordになるのを待ち、/v1/accounts/{account_id}/auth/passwordへ送信します。ログへ残さず、認証後に平文を保存しません。

Webhookはアカウント接続の前後どちらで作りますか？

接続前です。認証状態とメッセージはイベントで届き、欠落したメッセージpayloadの再配信は保証されません。

入電ワークフローを開始するイベントはどれですか？

message.receivedを使い、data.message.directionがinboundであることを確認します。処理前に必ずHMAC署名を検証します。

次のステップ

Telegram認証ガイドを開き、コードまたはQRを選択してください。Webhookを先に保護し、その後メッセージングアカウントを作成して認証します。

参照元

公式情報の確認日：2026-08-13

• Telegram: Creating your Telegram Application
• Telegram: Login via QR code
• Telegram: User Authorization
• Telegram Bot API