Skip to main content
X は chat.receivedchat.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_minutesstart_timeend_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= — 削除
リクエストボディと必要なスコープは各ルートの OpenAPI 操作で定義されています。X Activity API(XAA)サブスクリプションの作成には、監視するユーザーに対するユーザーコンテキスト認可(OAuth 2.0 のユーザーコンテキストと関連スコープ。チャットイベントには dm.read など)が必要です。 Webhook: HTTPS エンドポイントでイベントを終端する場合は、POST /2/webhooks で Webhook を登録し、CRC チャレンジに応答し、POST /2/activity/subscriptionswebhook_id を参照するアクティビティサブスクリプションを作成します(OpenAPI の Webhooks と Activity 操作を参照)。Python/TypeScript XDK では、SDK のバージョンに含まれていれば Webhook とアクティビティ用のヘルパーを公開している場合があります。
送信コピーも必要な場合は chat.sent も購読してください。他の言語では同じ /2/activity/* HTTPS ルートを直接呼び出します(サブスクリプション作成にはユーザーコンテキストトークン、ストリームには App の Bearer トークン)。

2. CRC(Webhook のみ)

Webhook を使う場合は、Challenge-Response Check(GET crc_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" とスネークケースのフィールドを使います。
代わりに鍵マップを自分の手で保持したい場合、extract_conversation_keysconversation_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 で重複排除してください