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 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 — 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= — deletar
Os corpos de requisição e os escopos necessários são definidos na operação OpenAPI de cada rota. Criar uma assinatura X Activity API (XAA) requer autorização em contexto de usuário (OAuth 2.0 em 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, 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.
Assine também 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 (GET crc_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.
Para manter os mapas de chave em suas próprias mãos, 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_keys para 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_uuid e mensagens pelo message_id assinado