Skip to main content
O X entrega 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 — criar
  • GET /2/activity/subscriptions — listar (paginado)
  • PUT /2/activity/subscriptions/{subscription_id} — atualizar
  • DELETE /2/activity/subscriptions/{subscription_id} ou DELETE /2/activity/subscriptions?ids= — excluir
Corpos de requisição e escopos requeridos estão definidos na operação OpenAPI para cada rota. Criar uma assinatura da X Activity API (XAA) requer autorização de contexto de usuário (OAuth 2.0 de contexto de usuário com os escopos relevantes, como 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.
Inscreva-se também em 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 (GET crc_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 entregas por event_uuid; deduplique mensagens pelo message_id carregado no evento descriptografado — ele faz parte do conteúdo assinado, enquanto os sequence ids são metadados atribuídos pelo backend e não assinados. Os snippets abaixo usam os dois armazenamentos de sessão opcionais para o handler mais curto: set_signing_keys mantém 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, para que decrypt_event precise apenas do evento. Quando um payload carrega conversation_key_change_event, passe-o antes por decrypt_events: isso verifica a mudança de chave e, com o cache ativo, retém sua chave para a chamada de decrypt_event. Prefere não manter 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 snake_case.
Para manter os mapas de chaves em suas próprias mãos, extract_conversation_keys descriptografa as chaves de conversation_key_change_event e decrypt_event aceita-as (e as chaves de assinatura do remetente) como argumentos explícitos — um argumento não vazio explícito sempre vence sobre os armazenamentos. Histórico: 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
  • Defina os armazenamentos de sessão uma vez: set_signing_keys para todos os participantes, set_cache_keys(true) para as chaves de conversa
  • Aplique blobs de mudança de chave (via decrypt_events) antes de descriptografar mensagens dependentes
  • Deduplique entregas por event_uuid e mensagens pelo message_id assinado