chat.received, chat.sent e atividades relacionadas do X Chat com texto cifrado no payload. Descriptografe com o Chat XDK.
Tipos de eventos privados do X Chat requerem autorização para o usuário que você monitora. Anexos de arquivos criptografados do X Chat usam
media_hash_key e o download de mídia do X Chat — não expansions=attachments.media_keys / media.fields=variants da Post API.
Tipos de eventos
1. Escolha a entrega
Stream de atividades (geralmente o mais simples para bots):GET /2/activity/stream com um Bearer token de app (opcional backfill_minutes, start_time, end_time por OpenAPI). Filtre no lado do cliente para chat.received / chat.sent.
Assinaturas de atividade: gerencie assinaturas duráveis com:
POST /2/activity/subscriptions— criarGET /2/activity/subscriptions— listar (paginado)PUT /2/activity/subscriptions/{subscription_id}— atualizarDELETE /2/activity/subscriptions/{subscription_id}ouDELETE /2/activity/subscriptions?ids=— excluir
dm.read para eventos de chat) para o usuário cuja atividade você monitora.
Webhooks: se você terminar eventos em seu endpoint HTTPS, registre um webhook com POST /2/webhooks, responda aos desafios CRC e depois crie suas assinaturas de atividade com POST /2/activity/subscriptions, referenciando seu webhook_id (veja operações de Webhooks e Activity no OpenAPI). O XDK Python/TypeScript pode expor helpers para webhooks e atividade quando sua versão do SDK os incluir.
- Python
- TypeScript
chat.sent se precisar de cópias de saída. Outras linguagens: chame diretamente as mesmas rotas HTTPS /2/activity/* (token de contexto de usuário para criar assinaturas, Bearer token de app para o stream).
2. CRC (apenas webhooks)
Se você usa webhooks, responda aos Challenge-Response Checks (GETcrc_token) com HMAC-SHA256 do token usando seu consumer secret, no formato JSON que seu produto de webhook espera (tipicamente sha256=<base64>).
3. Descriptografar com o Chat XDK
Campos ao vivo:payload.encoded_event, opcional payload.conversation_key_change_event. Deduplique por event_uuid.
JavaScript usa tipos de evento em camelCase (message); outros bindings usam "Message" e campos snake_case.
- Python
- TypeScript
- Rust
- Go
- C#
- Java
GET /2/chat/conversations/{id}/events + decrypt_events — veja Guia de introdução.
Formato do payload (ao vivo)
Práticas
- Verifique assinaturas de webhook conforme os requisitos de cada plataforma
- Faça cache das chaves de conversa e das chaves públicas dos remetentes
- Aplique blobs de mudança de chave antes de descriptografar mensagens dependentes
- Deduplique por
event_uuid