chat.received、chat.sent、および関連する X Chat のアクティビティを、ペイロードに暗号文を含めて配信します。Chat XDK で復号してください。
プライベート X Chat のイベントタイプでは、監視するユーザーに対する認可が必要です。暗号化された X Chat のファイル添付は
media_hash_key と X Chat メディアダウンロードを使い、Post API の expansions=attachments.media_keys / media.fields=variants ではありません。
イベントタイプ
1. 配信方式を選ぶ
アクティビティストリーム(多くのボットで最もシンプル): App の Bearer トークンでGET /2/activity/stream(OpenAPI に従いオプションで backfill_minutes、start_time、end_time)。クライアント側で chat.received / chat.sent をフィルタします。
アクティビティサブスクリプション: 永続的なサブスクリプションを次で管理します。
POST /2/activity/subscriptions— 作成GET /2/activity/subscriptions— 一覧(ページング)PUT /2/activity/subscriptions/{subscription_id}— 更新DELETE /2/activity/subscriptions/{subscription_id}またはDELETE /2/activity/subscriptions?ids=— 削除
dm.read など)が必要です。
Webhook: HTTPS エンドポイントでイベントを終端する場合は、POST /2/webhooks で Webhook を登録し、CRC チャレンジに応答し、POST /2/activity/subscriptions で webhook_id を参照するアクティビティサブスクリプションを作成します(OpenAPI の Webhooks と Activity 操作を参照)。Python/TypeScript XDK では、SDK のバージョンに含まれていれば Webhook とアクティビティ用のヘルパーを公開している場合があります。
- Python
- TypeScript
chat.sent も購読してください。他の言語では同じ /2/activity/* HTTPS ルートを直接呼び出します(サブスクリプション作成にはユーザーコンテキストトークン、ストリームには App の Bearer トークン)。
2. CRC(Webhook のみ)
Webhook を使う場合は、Challenge-Response Check(GETcrc_token)に対して、消費者シークレットを使ってトークンを HMAC-SHA256 したものを、Webhook プロダクトが期待する JSON 形式(通常は sha256=<base64>)で返してください。
3. Chat XDK で復号する
ライブフィールド:payload.encoded_event、オプションで payload.conversation_key_change_event。配信は event_uuid で重複排除してください。メッセージは復号済みイベントに含まれる message_id で重複排除してください——これは署名済みコンテンツの一部です。シーケンス ID はバックエンドで割り当てられる署名なしのメタデータです。
以下のスニペットは、最も短いハンドラーになるように 2 つのオプションセッションストアを使います:set_signing_keys は参加者の公開鍵を保持(一度 public-keys エンドポイント から取得)し、set_cache_keys(true) は各会話の検証済み鍵を保持するので、decrypt_event はイベントだけで済みます。ペイロードが conversation_key_change_event を含む場合は、まずそれを decrypt_events に通してください:これは鍵変更を検証し、キャッシュがオンなら以後の decrypt_event 呼び出しのために鍵を保持します。インスタンス状態を持たない方式が好ましい場合は、呼び出しごとに鍵を渡してください——このセクションの末尾のノートを参照してください。
JavaScript は camelCase のイベントタイプ(message)を使いますが、他のバインディングは "Message" とスネークケースのフィールドを使います。
- Python
- TypeScript
- Rust
- Go
- C#
- Java
extract_conversation_keys は conversation_key_change_event から鍵を復号し、decrypt_event はそれら(および送信者の署名鍵)を明示的な引数として受け取ります——明示的で空でない引数は常にストアより優先されます。
履歴:GET /2/chat/conversations/{id}/events + decrypt_events — はじめに を参照してください。
ペイロード形状(ライブ)
プラクティス
- プラットフォーム要件に沿って Webhook の署名を検証してください
- セッションストアは一度セットしてください:参加者全員に対して
set_signing_keys、会話鍵にはset_cache_keys(true) - 依存メッセージを復号する前に鍵変更ブロブを適用してください(
decrypt_events経由) - 配信は
event_uuidで、メッセージは署名済みのmessage_idで重複排除してください