Skip to main content
Imagens e outros arquivos usam a mesma chave de conversa do texto. Criptografe bytes com o Chat XDK (encrypt_stream / decrypt_stream), faça upload via as rotas /2/chat/media/upload (barra lateral Referência da API → Mídia) e depois anexe media_hash_key em encrypt_message. Inclua media.write junto com seus escopos de DM ao fazer upload. Use IDs de conversa com hífen nos caminhos (:-). Prefira MIME/dimensões dos bytes descriptografados. Este caminho não é o modelo de mídia de Posts (expansions=attachments.media_keys, media.fields=variants etc.). Esses parâmetros se aplicam a Posts; blobs E2EE do X Chat são endereçados por media_hash_key e download de mídia do X Chat.

Criptografar

encrypt_stream / decrypt_stream processam o payload inteiro em memória. Para arquivos grandes, stream_encryptor() / stream_decryptor() retornam objetos incrementais (StreamEncryptor / StreamDecryptor): alimente com chunks via push e depois chame finish uma vez — finish gera erro se o stream foi truncado.

Upload

Use os corpos de requisição nas páginas OpenAPI em Referência da API → Mídia. Prefira o tamanho do blob criptografado onde o tamanho for necessário. Finalizar retorna media_hash_key para anexos e download. Refaça tentativas de 5xx transitórios com backoff. Python/TypeScript podem usar o XDK quando há helpers de mídia; caso contrário, faça POST com um token Bearer em qualquer linguagem.

Enviar com um anexo

Criptografe com um anexo de mídia e depois faça POST do corpo send-message (mesmo mapeamento de campo de Primeiros passos). O SDK gera o message_id e o retorna no payload — envie esse valor e reutilize o mesmo payload em retentativas para que um ID nunca seja gerado duas vezes.
O par chave/versão da conversa pode ser totalmente omitido: com set_cache_keys(true) habilitado, encrypt_message resolve a chave e a versão a partir da mudança de chave mais recente verificada da conversa (veja Primeiros passos).

Baixar e descriptografar

Caminho: GET /2/chat/media/{conversation_id}/{media_hash_key}. O corpo da resposta é texto cifrado. Em mensagens de entrada, leia media_hash_key dos anexos descriptografados / media_hashes. Escolha a chave pela versão da chave do evento. Cada evento de mensagem descriptografado carrega a keyVersion (JS; key_version nos outros bindings) sob a qual seu conteúdo foi criptografado. Descriptografe um anexo com a chave da conversa para essa versão — conversationKeys.keys[event.keyVersion] — não a mais recente. Após uma rotação de chave (por exemplo, uma adição de membro), a chave mais recente não conseguirá descriptografar mídia anexada a mensagens mais antigas.

Dicas

  • Use a mesma versão da chave da conversa usada quando a mídia foi criptografada
  • Não registre mídia em texto simples nem chaves em bruto
  • Detecte o MIME após descriptografar
  • Clientes web: criptografe/descriptografe no cliente quando possível; mantenha os tokens OAuth no seu servidor
Esquemas completos de requisição e resposta para cada rota de mídia estão em Referência da API → Mídia na barra lateral (inicializar upload, append de chunk, finalizar upload e baixar mídia).