Skip to main content
X는 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. 전달 방식 선택

활동 스트림(봇에 가장 간단한 경우가 많음): 앱 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= — 삭제
요청 본문과 필요한 스코프는 각 경로의 OpenAPI 작업에 정의되어 있습니다. X Activity API(XAA) 구독을 생성하려면 활동을 모니터링할 사용자에 대한 사용자 컨텍스트 권한 부여(관련 스코프—예: 채팅 이벤트에 대한 dm.read—를 갖춘 OAuth 2.0 사용자 컨텍스트)가 필요합니다. 웹훅: HTTPS 엔드포인트에서 이벤트를 종단하는 경우, POST /2/webhooks로 웹훅을 등록하고, CRC 챌린지를 통과한 다음, webhook_id를 참조하여 POST /2/activity/subscriptions로 활동 구독을 생성하세요(OpenAPI의 Webhooks와 Activity 작업 참고). Python/TypeScript XDK는 해당 SDK 버전에 포함된 경우 웹훅과 활동에 대한 헬퍼를 노출할 수 있습니다.
발신 사본이 필요하다면 chat.sent도 구독하세요. 다른 언어: 동일한 /2/activity/* HTTPS 경로를 직접 호출하세요(구독 생성에는 사용자 컨텍스트 토큰, 스트림에는 앱 Bearer 토큰).

2. CRC(웹훅 전용)

웹훅을 사용하는 경우, 웹훅 제품이 기대하는 JSON 형식(일반적으로 sha256=<base64>)으로 컨슈머 시크릿을 사용해 토큰의 HMAC-SHA256으로 Challenge-Response Check(GET crc_token)에 응답하세요.

3. Chat XDK로 복호화

실시간 필드: payload.encoded_event, 선택적 payload.conversation_key_change_event. 전달은 **event_uuid**로 중복 제거하고, 메시지는 복호화된 이벤트에 포함된 **message_id**로 중복 제거하세요—이는 서명된 내용의 일부이며, sequence ID는 백엔드가 할당한 서명되지 않은 메타데이터입니다. 아래 스니펫은 가장 짧은 핸들러를 위해 두 개의 선택적 세션 저장소를 사용합니다: set_signing_keys는 참여자의 공개 키(공개 키 엔드포인트에서 한 번 가져옴)를 보관하고, set_cache_keys(true)는 각 대화의 검증된 키를 보관하므로 decrypt_event가 이벤트만으로 충분합니다. 페이로드에 conversation_key_change_event가 포함되면 먼저 decrypt_events를 통해 실행하세요: 이는 키 변경을 검증하고, 캐싱이 켜져 있으면 decrypt_event 호출을 위해 그 키를 보존합니다. 인스턴스 상태를 원하지 않으신가요? 대신 호출별로 키를 전달하세요—이 섹션 끝의 노트를 참고하세요. JavaScript는 카멜케이스 이벤트 타입(message)을 사용하고, 다른 바인딩은 "Message"와 스네이크케이스 필드를 사용합니다.
대신 키 맵을 직접 관리하려면, extract_conversation_keysconversation_key_change_event에서 키를 복호화하고 decrypt_event는 이를(그리고 발신자의 서명 키를) 명시적 인수로 받습니다—명시적으로 비어 있지 않은 인수는 항상 저장소보다 우선합니다. 히스토리: GET /2/chat/conversations/{id}/events + decrypt_events시작하기 참고.

페이로드 형태(실시간)


관행

  • 플랫폼 요구사항에 따라 웹훅 서명을 검증하세요
  • 세션 저장소를 한 번 설정하세요: 모든 참여자에 대한 set_signing_keys, 대화 키에 대한 set_cache_keys(true)
  • 종속된 메시지를 복호화하기 전에 키 변경 blob을(decrypt_events를 통해) 적용하세요
  • 전달은 event_uuid로, 메시지는 서명된 message_id로 중복 제거하세요