chat.received, chat.sent y actividad relacionada de X Chat con texto cifrado en el payload. Descifra con el Chat XDK.
Los tipos de evento privados de X Chat requieren autorización del usuario que monitoreas. Los adjuntos de archivos 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 Post API.
Tipos de evento
1. Elige el modo de entrega
Activity stream (a menudo lo más simple para bots):GET /2/activity/stream con un Bearer token de app (opcional backfill_minutes, start_time, end_time según OpenAPI). Filtra en el cliente por chat.received / chat.sent.
Suscripciones de Activity: gestiona suscripciones duraderas con:
POST /2/activity/subscriptions— crearGET /2/activity/subscriptions— listar (paginado)PUT /2/activity/subscriptions/{subscription_id}— actualizarDELETE /2/activity/subscriptions/{subscription_id}oDELETE /2/activity/subscriptions?ids=— eliminar
dm.read para eventos de chat) para el usuario cuya actividad monitoreas.
Webhooks: si terminas los eventos en tu endpoint HTTPS, registra un webhook con POST /2/webhooks, pasa los challenges CRC y luego crea tus suscripciones de actividad con POST /2/activity/subscriptions, haciendo referencia a tu webhook_id (consulta las operaciones Webhooks y Activity en OpenAPI). El XDK de Python/TypeScript puede exponer helpers para webhooks y actividad cuando tu versión del SDK los incluya.
- Python
- TypeScript
chat.sent si necesitas copias salientes. Otros lenguajes: llama directamente a las mismas rutas HTTPS /2/activity/* (token de contexto de usuario para crear suscripciones, Bearer token de app para el stream).
2. CRC (solo webhooks)
Si usas webhooks, responde a los Challenge-Response Checks (GETcrc_token) con HMAC-SHA256 del token usando el consumer secret, en la forma JSON que tu producto de webhook espera (típicamente sha256=<base64>).
3. Descifra con el Chat XDK
Campos en vivo:payload.encoded_event, opcional payload.conversation_key_change_event. Deduplica las entregas por event_uuid; deduplica los mensajes por el message_id que lleva el evento descifrado—forma parte del contenido firmado, mientras que los sequence ids son metadatos sin firmar asignados por el backend.
Los snippets de abajo usan los dos almacenes de sesión opcionales para el handler más corto: set_signing_keys mantiene las claves públicas de los participantes (obtenidas una vez del endpoint de claves públicas), y set_cache_keys(true) conserva la clave verificada de cada conversación, así decrypt_event solo necesita el evento. Cuando un payload lleva conversation_key_change_event, pásalo antes por decrypt_events: eso verifica el cambio de clave y, con la caché activa, retiene su clave para la llamada a decrypt_event. ¿Prefieres no tener estado en la 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); los demás bindings usan "Message" y campos snake_case.
- Python
- TypeScript
- Rust
- Go
- C#
- Java
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 del webhook según los requisitos de la plataforma
- Configura los almacenes de sesión una vez:
set_signing_keyspara todos los participantes,set_cache_keys(true)para las claves de conversación - Aplica los blobs de cambio de clave (mediante
decrypt_events) antes de descifrar los mensajes dependientes - Deduplica las entregas por
event_uuidy los mensajes por elmessage_idfirmado