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)

chat.received

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