Skip to main content
X entrega chat.received, chat.sent y actividad de X Chat relacionada con texto cifrado en el payload. Descifra con el Chat XDK. Los tipos de eventos privados de X Chat necesitan autorización para el usuario que monitorizas. Los adjuntos cifrados de X Chat usan media_hash_key y la descarga de multimedia de X Chat—no expansions=attachments.media_keys / media.fields=variants de la API de Posts.

Tipos de evento


1. Elige la entrega

Activity stream (a menudo lo más simple para bots): GET /2/activity/stream con un token Bearer de app (opcionales backfill_minutes, start_time, end_time según OpenAPI). Filtra del lado del cliente para chat.received / chat.sent. Suscripciones de Activity: administra suscripciones duraderas con:
  • POST /2/activity/subscriptions — crear
  • GET /2/activity/subscriptions — listar (paginado)
  • PUT /2/activity/subscriptions/{subscription_id} — actualizar
  • DELETE /2/activity/subscriptions/{subscription_id} o DELETE /2/activity/subscriptions?ids= — eliminar
Los cuerpos de solicitud y los alcances requeridos están definidos en la operación OpenAPI de cada ruta. Crear una suscripción de la X Activity API (XAA) requiere autorización en contexto de usuario (contexto de usuario OAuth 2.0 con los alcances relevantes, como dm.read para eventos de chat) del usuario cuya actividad monitorizas. Webhooks: si terminas los eventos en tu endpoint HTTPS, registra un webhook con POST /2/webhooks, pasa los desafíos CRC, luego crea tus suscripciones de Activity con POST /2/activity/subscriptions, referenciando tu webhook_id (consulta las operaciones Webhooks y Activity en OpenAPI). El XDK de Python/TypeScript puede exponer helpers para webhooks y activity cuando la versión de tu SDK los incluya.
Suscríbete también a chat.sent si necesitas copias salientes. Otros lenguajes: llama directamente a las mismas rutas HTTPS /2/activity/* (token en contexto de usuario para crear suscripciones, token Bearer de app para el stream).

2. CRC (solo webhooks)

Si usas webhooks, responde a los Challenge-Response Checks (GET crc_token) con HMAC-SHA256 del token usando tu consumer secret, en la forma JSON que espera tu producto de webhooks (típicamente sha256=<base64>).

3. Descifrar con el Chat XDK

Campos en vivo: payload.encoded_event, opcional payload.conversation_key_change_event. Deduplica las entregas con event_uuid; deduplica los mensajes con el message_id que lleva el evento descifrado—forma parte del contenido firmado, mientras que los sequence ids son metadatos no firmados asignados por el backend. Los snippets a continuación usan los dos almacenes de sesión opcionales para el handler más corto: set_signing_keys guarda las claves públicas de los participantes (obtenidas una vez del endpoint public-keys), y set_cache_keys(true) mantiene la clave verificada de cada conversación, así que decrypt_event solo necesita el evento. Cuando un payload lleva conversation_key_change_event, pásalo primero por decrypt_events: eso verifica el cambio de clave y, con la caché activada, retiene su clave para la llamada a decrypt_event. ¿Prefieres no tener estado de instancia? Pasa las claves por llamada en su lugar—consulta la nota al final de esta sección. JavaScript usa tipos de evento en camelCase (message); otros bindings usan "Message" y campos snake_case.
Para mantener los mapas de claves bajo tu control en su lugar, extract_conversation_keys descifra las claves de conversation_key_change_event y decrypt_event las acepta (junto con las claves de firma del remitente) como argumentos explícitos—un argumento explícito no vacío siempre gana sobre los almacenes. Historial: GET /2/chat/conversations/{id}/events + decrypt_events — consulta Primeros pasos.

Forma del payload (en vivo)


Prácticas

  • Verifica las firmas de webhooks según los requisitos de la plataforma
  • Configura los almacenes de sesión una vez: set_signing_keys para todos los participantes, set_cache_keys(true) para las claves de conversación
  • Aplica los blobs de key-change (vía decrypt_events) antes de descifrar los mensajes dependientes
  • Deduplica las entregas con event_uuid y los mensajes con el message_id firmado