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 por event_uuid. JavaScript usa tipos de evento em camelCase (message); outros bindings usam "Message" e campos snake_case.
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
  • 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