Skip to main content
画像やその他のファイルは、テキストと同じ会話鍵を使用します。Chat XDK でバイト列を暗号化し(encrypt_stream / decrypt_stream)、/2/chat/media/upload ルート(サイドバー API リファレンス → Media)経由でアップロードし、encrypt_messagemedia_hash_key を添付します。 アップロード時は DM スコープに加え media.write を含めてください。パスにはハイフン付き会話 ID を使用します(:-)。MIME/寸法は復号後のバイトから取得することが望ましいです。 このパスは Posts のメディアモデル(expansions=attachments.media_keysmedia.fields=variants など)ではありません。それらのパラメーターは Posts に適用されます。E2EE の X Chat ブロブは media_hash_key と X Chat メディアダウンロードでアドレッシングされます。

暗号化

encrypt_stream / decrypt_stream はペイロード全体をメモリ内で処理します。大きなファイルの場合は、stream_encryptor() / stream_decryptor() が増分オブジェクト(StreamEncryptor / StreamDecryptor)を返します:push でチャンクを送り込み、最後に一度 finish を呼びます——ストリームが切り捨てられていた場合、finish はエラーになります。

アップロード

API リファレンス → Media の OpenAPI ページのリクエストボディを使用してください。サイズが必要な場合は暗号化されたブロブサイズを優先してください。Finalize は添付やダウンロードのための media_hash_key を返します。一時的な 5xx はバックオフしてリトライしてください。Python/TypeScript ではメディアヘルパーが存在すれば XDK を使えます。そうでない場合はどの言語でも Bearer トークンで POST してください。

添付付きで送信する

メディア添付付きで暗号化し、send-message ボディを POST します(はじめに と同じフィールドマッピング)。SDK が message_id を生成してペイロード上で返します——その値を送信し、リトライ時は同じペイロードを再利用することで、ID が二度発行されないようにします。
会話鍵のペアは完全に省略することもできます:set_cache_keys(true) が有効なら、encrypt_message は会話の最新の検証済み鍵変更から鍵とバージョンを解決します(はじめにを参照)。

ダウンロードと復号

パス:GET /2/chat/media/{conversation_id}/{media_hash_key}。レスポンスボディは暗号文です。受信メッセージでは、復号された添付ファイル/media_hashes から media_hash_key を読み取ります。 イベントの鍵バージョンで鍵を選んでください。 復号された各メッセージイベントには、そのコンテンツが暗号化された keyVersion(JS。他のバインディングでは key_version)が付いています。そのバージョンに対応する会話鍵で添付を復号してください——最新の鍵ではなく conversationKeys.keys[event.keyVersion] を使います。鍵ローテーション後(たとえばメンバー追加の後)、最新の鍵では古いメッセージに添付されたメディアを復号できません。

ヒント

  • メディアが暗号化されたときと同じ会話鍵(およびバージョン)を使用してください
  • 平文メディアや生の鍵をログに出力しないでください
  • MIME は復号後に検出してください
  • Web クライアント:可能な限りクライアントで暗号化/復号し、OAuth トークンはサーバー側に保持してください
各メディアルート(アップロード初期化、チャンク追加、アップロード完了、メディアダウンロード)の完全なリクエスト/レスポンススキーマは、サイドバーの API リファレンス → Media にあります。