chat.received, chat.sent e atividades relacionadas do X Chat com texto cifrado no payload. Descriptografe com o Chat XDK.
Tipos privados de evento do X Chat requerem autorização do usuário monitorado. Anexos de arquivos criptografados do X Chat usam
media_hash_key e o download de mídia do X Chat, não os parâmetros da API de Posts expansions=attachments.media_keys / media.fields=variants.
Tipos de evento
1. Escolha a entrega
Activity stream (geralmente mais simples para bots):GET /2/activity/stream com um Bearer token de app (opcional backfill_minutes, start_time, end_time conforme OpenAPI). Filtre no cliente por 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=: deletar
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, passe pelos desafios de CRC e depois crie suas assinaturas de atividade com POST /2/activity/subscriptions, referenciando seu webhook_id (veja as operações de Webhooks e Activity no OpenAPI). Os XDKs de Python/TypeScript podem expor helpers para webhooks e atividade quando sua versão do SDK os incluir.
- Python
- TypeScript
chat.sent se você precisar de cópias de saída. Outras linguagens: chame as mesmas rotas HTTPS /2/activity/* diretamente (token em contexto de usuário para criar assinaturas, Bearer token de app para o stream).
2. CRC (apenas webhooks)
Se você usar webhooks, responda aos Challenge-Response Checks (GETcrc_token) com HMAC-SHA256 do token usando seu consumer secret, no formato JSON esperado pelo seu produto de webhook (normalmente sha256=<base64>).
3. Descriptografe com o Chat XDK
Campos ao vivo:payload.encoded_event, opcional payload.conversation_key_change_event. Deduplique entregas por event_uuid; deduplique mensagens pelo message_id carregado no evento descriptografado. Ele faz parte do conteúdo assinado, enquanto sequence ids são metadados não assinados atribuídos pelo backend.
Os snippets abaixo usam os dois armazenamentos de sessão opcionais para o handler mais curto: set_signing_keys guarda as chaves públicas dos participantes (buscadas uma vez do endpoint de chaves públicas) e set_cache_keys(true) mantém a chave verificada de cada conversa, de modo que decrypt_event só precisa do evento. Quando um payload traz conversation_key_change_event, execute-o antes por decrypt_events: isso verifica a mudança de chave e, com caching ativado, retém sua chave para a chamada de decrypt_event. Prefere nenhum estado na instância? Passe as chaves por chamada; veja a nota no final desta seção.
JavaScript usa tipos de evento em camelCase (message); outros bindings usam "Message" e campos em snake_case.
- Python
- TypeScript
- Rust
- Go
- C#
- Java
extract_conversation_keys descriptografa as chaves de conversation_key_change_event e decrypt_event as aceita (junto com as chaves de assinatura do remetente) como argumentos explícitos; um argumento explícito e não vazio sempre prevalece sobre os armazenamentos.
Histórico: GET /2/chat/conversations/{id}/events + decrypt_events; veja Primeiros passos.
Formato do payload (ao vivo)
chat.received
Práticas
- Verifique assinaturas de webhook conforme os requisitos da plataforma
- Defina os armazenamentos de sessão uma vez:
set_signing_keyspara todos os participantes,set_cache_keys(true)para chaves de conversa - Aplique blobs de mudança de chave (via
decrypt_events) antes de descriptografar mensagens dependentes - Deduplique entregas por
event_uuide mensagens pelomessage_idassinado