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)
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