ガイド September 24, 2026

Telegram getFile：期限切れのダウンロードリンクを安全に復旧する

Telegram ボットのファイルダウンロードリンクが期限切れになったら、ファイルの file_id で getFile を再度呼び出し、返された file_path を使います。Telegram が保証する有効期間は最低1時間であり、永久ではありません。file_unique_id はダウンロード用の識別子には使えません。この復旧方法は公式 Bot API のものです。統合 webhook で受け取る一時的な添付 URL には別の仕様が適用されます。

要点

メディアメッセージの受信と、ファイル本体の保存は別です。
ファイル識別子とメッセージの文脈を保存し、URL は一時的な取得先として扱います。
Bot API のリンクが期限切れになったら、同じ URL を無限に再試行せず getFile で再取得します。
Telegram の有効期間や更新方法を UnifyPort の添付 URL に適用しないでください。

getFile の戻り値と保存すべき情報

Telegram Bot API リファレンスでは、getFile はファイルの基本情報を取得し、ダウンロードを準備するメソッドです。成功時には File オブジェクトを返します。識別子の用途は次のように異なります。

値	公式の用途	アプリケーションでの推奨用途
`file_id`	ファイルのダウンロードや再利用	受信したボットの識別情報とともに保存し、後の `getFile` に使う
`file_unique_id`	時間やボットが異なってもファイルを識別する。ダウンロードや再利用には使えない	関連付けに使う。ダウンロード識別子の代用にはしない
`file_path`	準備されたファイルのダウンロードパス	最新の応答を使い、古いパスを恒久的な場所と見なさない
`file_name`、`mime_type`	送信者が指定する任意のドキュメントメタデータ	受信メッセージにあれば保存し、使用前に検証する

元のチャットとメッセージの識別子も保存してください。ファイルの同一性は会話へのアクセス権ではありません。別のチャットに同じメディアが現れても、保存済みコピーへのアクセスを自動的に許可してはいけません。

これらは Bot API のフィールドであり、UnifyPort のイベントに追加するフィールドではありません。接続方式を選ぶ段階なら、Bot API webhook と統合受信 webhook の比較から確認してください。

Telegram ファイルのダウンロード失敗を切り分ける

受信トレイにサムネイルが表示されるかどうかではなく、実際に失敗した段階から復旧方法を選びます。

状況	次の確認項目	復旧の境界
`getFile` が失敗する	ボットの認証情報、実際の `file_id`、返されたエラー、ファイルサイズ	再試行の前にリクエストや対応する取得方法を修正する
以前使えたリンクが使えない	新しい `getFile` の結果	新しい取得先で再試行する。すべての HTTP エラーを期限切れと判断しない
ダウンロードがタイムアウトする	ネットワーク、ワーカーのタイムアウト、ストレージの可用性	再試行回数を制限し、期限切れが疑わしければ取得先を再取得する
ダウンロード後の解析に失敗する	実際のデータとパーサーの対応形式	リンクを更新しても未対応形式や不正な内容は直らない
webhook はあるが保存済みファイルがない	永続化したダウンロードジョブとワーカーの結果	イベント受信とファイル保存を別の到達点として扱う

Telegram は現在、API リファレンスと Bots FAQで、ホスト型 Bot API のダウンロード上限を20 MBとしています。アップロード上限や Telegram クライアント全体の能力とは区別してください。API リファレンスには、ローカル Bot API サーバーではこのサイズ制限なしでダウンロードできることも記載されています。これはインフラの選択であり、ホスト型のエンドポイントにパラメーターを追加して上限を変えるものではありません。

最低1時間という保証は、1時間待つよう求めるものでも、ちょうど1時間で必ず失効するという意味でもありません。期限切れ後に getFile を再度呼び出して新しいリンクを得るのが、文書化された方法です。

確実な受信の後にファイルを永続化する

以下は推奨するアプリケーション設計であり、Telegram の配信保証ではありません。

受信した更新と、ダウンロードジョブに必要なメタデータを保存します。ジョブを永続化してから受信を確認応答します。
ワーカーがダウンロード直前に取得先を解決します。長いキューに古くなる URL を大量に置かないようにします。
非公開の一時ストレージへストリーミングし、独自の容量・時間制限を設けます。送信者のファイル名と MIME タイプは信頼できないメタデータとして扱います。
ダウンロードと内容検査が完了してから、自社管理ストレージの参照を公開します。未完成のファイルをサポート画面や AI 処理に渡してはいけません。
失敗時は機密情報を除いた原因を保存し、制限付きの再試行を判断します。復旧できなければ「添付ファイルを利用できません」と表示し、「メッセージ未受信」と誤表示しないでください。

ファイル名やオブジェクトキーはアプリケーション側で生成し、ユーザー指定のパスをそのまま使わないでください。ワーカーの接続先を制限し、任意のホストへサービス認証情報を転送せず、認証情報や署名付き URL を通常ログに残さない設計にします。イベントの署名検証に成功しても、添付文書を安全に開ける証明にはなりません。

遅延ジョブ、期限切れの取得先、サイズ超過、任意のファイル名の欠落、保存中のワーカー停止をテストしてください。合格条件は HTTP 成功だけではなく、正しい権限のある会話に利用可能なコピーか明確な失敗状態が届くことです。これは推奨テストであり、実測結果ではありません。

UnifyPort のメディアには別の復旧仕様がある

UnifyPort の非公式インターフェースは、接続したメッセージングアカウントのイベントを message.received に正規化します。標準イベントリファレンスには data.message.attachments[] と一時的な OSS 署名付き URL が記載されています。Telegram メディアのフィールド対応ガイドがフィールド保存を扱うのに対し、本記事はジョブ作成後のファイル可用性を扱います。

この経路では、次の境界を守ってください。

webhook 配信リファレンスに従って署名検証と永続化を行い、保存ポリシーに沿って利用可能な添付 URL を速やかに処理します。
URL がない場合を明示的に処理します。文書化された大容量ファイルの表現では attachments[].metadata.is_big_file を使い、url を省略します。メッセージ ID から URL を作らないでください。
正規化された添付に Bot API の file_id があると仮定したり、添付 URL を getFile に渡したりしないでください。
Bot API の1時間保証や20 MB上限を、UnifyPort の製品仕様として設定に転記しないでください。

UnifyPort の公開リファレンスには添付 URL の更新エンドポイントは記載されていません。また、REST によるメッセージ履歴取得 API や、取り逃したペイロードの再配信保証はありません。URL が使えず保存済みコピーもなければ、アカウント再接続で復旧できると約束しないでください。制約を記録し、必要に応じて権限を確認したうえで再送や手動対応を依頼します。

よくある質問

file_unique_id を getFile に使えますか？

使えません。Telegram はダウンロードや再利用に使えないと明記しています。ダウンロード用には file_id を保存します。

リンクは必ず1時間後に期限切れになりますか？

いいえ。保証されるのは最低1時間です。期限切れになったら getFile で新しいリンクを要求します。

ブラウザーや AI サービスに元の URL を渡すべきですか？

バックエンドでダウンロードし、アプリケーションの認可を通したストレージ参照を渡す方法を優先してください。表示のためだけに認証情報や一時的な署名付き URL を広く共有しないでください。

getFile で UnifyPort の添付 URL を更新できますか？

そのような相互運用は文書化されていません。それぞれの仕様に従い、存在しない更新操作を想定しないでください。

次のステップと出典

標準 webhook イベント仕様を確認し、下流の自動化に接続する前に、メディアワーカーへ保存成功・失敗の明確な状態を追加してください。

確認日：2026-09-24。

UnifyPort API

メッセージ連携を安定したプロダクトパイプラインへ。

まずは 1 つの API で送信を始め、標準イベントですべての inbound メッセージを業務システムへ戻しましょう。

API Key を取得 API リファレンスを見る