Telegram Botのディープリンク:startパラメーターとアカウント連携
Telegram Botのディープリンクは、プライベートチャットの /start コマンドでパラメーターを渡します。ただし、それだけではWebサイトのアカウントとTelegramユーザーが同一人物のものだと証明できません。パラメーターでサーバー側の保留中リクエストを参照し、Botが更新を受信した後、機密性の高いアカウント連携は明示的な確認を経て確定します。URLを開いた時点では完了ではありません。
要点
- 起動パラメーターは最大64文字で、英字、数字、アンダースコア、ハイフンを使用できます。
startはプライベートチャット用です。startgroupは別のグループ追加フローです。- キャンペーンコードは公開できますが、連携用トークンは推測困難・短期有効・一度限りにします。
- Botの利用開始と、既存Telegramメッセージングアカウントの認証は別の処理です。
Telegramのstartリンクが送るもの
TelegramのBot機能ドキュメントは、他のプラットフォームのアカウントとの連携を含め、ディープリンクの用途を説明しています。構文は https://t.me/<bot_username>?start=<parameter> です。山括弧部分は構文説明であり、実在するBotや本番用トークンではありません。
クライアントのディープリンク仕様には、Startボタンからパラメーター付きのBot起動操作を実行する動作が記載されています。画面の進行条件は、ブラウザーでのクリックや想定上の自動送信ではなく、実際に受信したコマンドにしてください。Botは /start airplane のようなテキストを受け取ります。ここではTelegram公式の例を使用しています。
許可される文字は A-Z、a-z、0-9、_、- で、最大64文字です。Telegramはバイナリなどの内容にbase64urlを推奨しています。ただし、エンコードは暗号化でも、信頼の証明でもありません。パスワード、bot token、API hash、メールアドレス、再利用可能なログイン資格情報をURLに含めないでください。
グループへの追加には、別途規定された startgroup を使います。グループ内のコマンドを、個人アカウント連携の証拠として扱わないでください。
振り分けと本人確認を分ける
| 用途 | 推奨するパラメーター | 受信から分かること |
|---|---|---|
| ヘルプ項目を開く | 許可リストにある公開トピックコード | ユーザーがその項目を要求したこと |
| キャンペーン流入を記録 | 公開キャンペーンコード | 流入元の情報。本人確認ではない |
| ログイン済みWebアカウントを連携 | 一度限りの不透明なサーバー側参照 | 確認が必要な保留中の関連付け |
ユーザーはコマンドを手入力したり、URLを共有したりできます。顧客番号がパラメーターに含まれていても、送信者がその顧客レコードの所有者とは限りません。推測困難なトークンでも転送や漏えいはあり得るため、ランダム性だけでは意図したアカウントの組み合わせを証明できません。
資格情報の区別が曖昧なら、先に Telegram API ID・API hashとbot tokenの比較を確認してください。起動パラメーターはアプリへの入力であり、これらの資格情報ではありません。
推奨するアカウント連携フロー
以下はアプリケーション設計の提案です。Telegramが提供するトークンサービスでも、新しいUnifyPortエンドポイントでもありません。
- ログイン済みWebセッションから開始する。 連携対象のアカウントを表示し、ユーザーの明示操作を求めます。通常のセッション保護とリクエスト偽造対策も適用します。
- サーバーに保留中リクエストを作成する。 暗号学的に安全でURLに使用できるランダムトークンを生成し、ハッシュ、対象Webアカウント、対象Bot、用途、有効期限、保留状態を保存します。これらはローカル管理項目であり、Telegram APIのフィールドではありません。有効期限は自社のリスク方針で決めます。Telegramのパラメーター形式がアプリのトークン寿命を定めるわけではありません。
- 実際の更新を検証する。 受信経路を認証し、対象Botのプライベートチャットメッセージだけを処理します。
/startを正確に解析し、文字種と長さを検証します。パラメーター内の自己申告IDではなく、受信メッセージの送信者を使用します。UpdateとMessageは Bot APIリファレンスで定義されています。 - 申請者を登録しても、即座にアクセス権を与えない。 保留中リクエストを観測したTelegramユーザーに原子的に関連付けます。期限切れや、登録後に別ユーザーが同じトークンを使う試行は拒否します。未確認のTelegram送信者にWebアカウントの詳細を開示しません。
- 元のWebセッションで組み合わせを確認する。 連携候補のTelegramユーザーを表示し、ログイン済みの所有者に承認を求めます。不一致なら取り消し、既存の連携を上書きしません。機密性が高い処理ではTelegram側にも適切な確認を加えます。
- 一度だけ確定し、最小限の監査記録を残す。 トークン消費と連携確定を原子的に行います。更新の重複やStartの再操作で、別の連携作成、連携先変更、特典の再付与が起きないようにします。解除は独立した認証済み操作として用意します。
生のトークンを分析基盤、ログ、スクリーンショット、問い合わせ票へ残さないでください。不正な試行にはレート制限を設けます。確認が来なければアクセス権を付与せず、リクエストを失効させます。
どの段階で止まったかを調べる
| 状況 | 次に確認すること |
|---|---|
| リンクは開くがコマンドが来ない | Bot名、Start操作、更新の受信経路 |
/start だけが届く | 通常の案内を表示。欠けた入力からアカウントを推測しない |
| パラメーターが無効・期限切れ | ログイン済みWeb画面から再申請してもらう |
| 同じ更新が再び届く | 保存済みの結果を使い、再連携しない |
| 別ユーザーが登録済みトークンを送る | 拒否して新しいフローを案内。自動で連携先を変えない |
| Botは受信したがWeb画面は待機中 | アプリの申請者登録・確認状態を調べる |
受信方式については Bot API webhookと統一受信webhookの比較を参照してください。ポーリングかwebhookかを選んでも、本人確認の問題は解決しません。
UnifyPortの適用範囲
この利用開始フローは公式Telegram Botのものです。一方、UnifyPortの Telegram認証リファレンスは、非公式インターフェースで既存アカウントを接続するコード、QR、セッションインポートを説明しています。Bot起動パラメーターでそのアカウントを認証したり、所有者の承認を代替したりすることはできません。
既存メッセージングアカウントからの受信が目的なら、この認証手順と message.received イベントを使用します。Botへのディープリンクが、接続済み一般アカウントの受信箱へ届くとは考えないでください。LINE、WhatsApp、Zaloも扱うサポート環境であっても、本人確認と連携管理はアプリ側で独立させます。
FAQ
リンクを開けば連携は完了しますか?
いいえ。Botコマンドとアプリ側の確認トランザクションを待つ必要があります。クリックだけでは受信も所有権も証明できません。
startパラメーターに顧客IDを入れてもよいですか?
機密性のない振り分け入力には使えますが、認可には使えません。連携にはランダムなサーバー側参照と明示確認を使用します。
base64urlで秘密情報を保護できますか?
いいえ。単なるエンコードです。機密情報はサーバーに置き、トークンが消費または失効するまでは連携URLも機密扱いにします。
Telegramユーザーアカウントのログインと同じですか?
別です。Botとの対話開始は、認証済みユーザーセッションを作成しません。必要な操作主体に合わせて方式を選んでください。
次のステップと出典
Telegramのディープリンク仕様を確認し、パラメーター欠落、リンク転送、期限切れ、重複更新、ユーザー不一致、取り消しをテストしてください。これは受け入れテストの提案であり、実行済み結果ではありません。
公式資料の確認日:2026-11-10。
メッセージ連携を安定したプロダクトパイプラインへ。
まずは 1 つの API で送信を始め、標準イベントですべての inbound メッセージを業務システムへ戻しましょう。