chat.received、chat.sent、および関連する X Chat アクティビティを、ペイロード内の暗号文とともに配信します。Chat XDK で復号します。
プライベート X Chat イベントタイプは、監視するユーザーに対する認可が必要です。暗号化された X Chat ファイル添付は、Post API の
expansions=attachments.media_keys / media.fields=variants ではなく、media_hash_key と X Chat メディアダウンロードを使用します。
イベントタイプ
1. 配信方法を選択する
アクティビティストリーム(ボットには多くの場合最もシンプル): アプリの Bearer トークンでGET /2/activity/stream(オプションの backfill_minutes、start_time、end_time は OpenAPI ごと)。クライアント側で 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 などチャットイベントに関連するスコープを持つ OAuth 2.0 ユーザーコンテキスト)が必要です。
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 ルートを直接呼び出します(サブスクリプションの作成にはユーザーコンテキストトークン、ストリームにはアプリの Bearer トークン)。
2. CRC(Webhook のみ)
Webhook を使用する場合、コンシューマシークレットを使ったトークンの HMAC-SHA256 を、Webhook 製品が期待する JSON 形式(通常はsha256=<base64>)で Challenge-Response Checks(GET crc_token)に応答してください。
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" と snake_case フィールドを使用します。
- Python
- TypeScript
- Rust
- Go
- C#
- Java
extract_conversation_keys が conversation_key_change_event から鍵を復号し、decrypt_event は(送信者の署名鍵とともに)それらを明示的な引数として受け取ります — 明示的な空でない引数は常にストアより優先されます。
履歴: GET /2/chat/conversations/{id}/events + decrypt_events — Getting Started を参照。
ペイロードの形(ライブ)
プラクティス
- プラットフォームの要件に従って Webhook 署名を検証する
- セッションストアを一度だけ設定する: 参加者全員に対して
set_signing_keys、会話鍵にはset_cache_keys(true) - 依存するメッセージを復号する前に、鍵変更 blob を(
decrypt_events経由で)適用する event_uuidで配信を、署名済みmessage_idでメッセージを重複排除する