> ## Documentation Index
> Fetch the complete documentation index at: https://x-preview-mintlify-d8d2882f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Referência do Chat XDK

> Referência do Chat XDK, o SDK de criptografia que cuida do gerenciamento de chaves, criptografia, descriptografia e assinatura do X Chat nas linguagens suportadas.

O **Chat XDK** cuida do gerenciamento de chaves, criptografia, descriptografia e assinatura do X Chat. Ele **não** chama a API HTTP do X — combine-o com o **XDK** de [Python](/xdks/python/overview) ou [TypeScript](/xdks/typescript/overview), ou com HTTPS e um token de acesso de usuário.

Passo a passo do app: [Primeiros passos](/pt/xchat/getting-started). Bots de exemplo: [chat-xdk/examples](https://github.com/xdevplatform/chat-xdk/tree/main/examples).

### Instalação

<Tabs>
  <Tab title="Python">
    ```bash theme={null}
    pip install chatxdk
    ```

    O pacote no PyPI é `chatxdk`; importe-o como `chat_xdk`. Requer Python 3.10+.
  </Tab>

  <Tab title="TypeScript">
    ```bash theme={null}
    npm install @xdevplatform/chat-xdk
    npm install juicebox-sdk   # optional peer dependency — required for setup()/unlock() secure key backup
    ```

    O mecanismo WASM compilado é entregue dentro do pacote — sem etapa de build. Requer Node.js 18+.
  </Tab>

  <Tab title="Rust">
    ```toml theme={null}
    [dependencies]
    # chat-xdk-core is not yet on crates.io — use the git dependency.
    # It exports both ChatCore and the async secure-key-backup Chat type.
    chat-xdk-core = { git = "https://github.com/xdevplatform/chat-xdk", tag = "v0.4.0" }

    # Required until thrift 0.24 is released on crates.io
    [patch.crates-io]
    thrift = { git = "https://github.com/apache/thrift.git", rev = "deb36fa409849de45973b04ffc3ce49d277ca90a" }
    ```
  </Tab>

  <Tab title="Go">
    ```bash theme={null}
    go get github.com/xdevplatform/chat-xdk/go/chatxdk
    ```

    Bibliotecas estáticas pré-compiladas estão incluídas (macOS arm64/amd64, Linux amd64 glibc/musl) — você precisa de um compilador C, mas não do Rust. Requer Go 1.21+.
  </Tab>

  <Tab title="C#">
    ```bash theme={null}
    dotnet add package XDevPlatform.ChatXdk
    ```

    O pacote é autocontido: bibliotecas nativas para macOS (arm64, x64), Linux (x64) e Windows (x64) são entregues dentro dele. Requer .NET 8+.
  </Tab>

  <Tab title="Java">
    ```xml theme={null}
    <dependency>
      <groupId>com.x</groupId>
      <artifactId>chatxdk</artifactId>
      <version>0.4.0</version>
    </dependency>
    ```

    Disponível no Maven Central. O jar inclui a biblioteca nativa para macOS (arm64, x64), Linux (x64) e Windows (x64) — sem necessidade de configurar `jna.library.path`. Importe de `com.x.chatxdk`. Requer JDK 17+.
  </Tab>
</Tabs>

***

## Início rápido

Carregue as chaves, defina sua identidade uma vez, descriptografe um backlog, descriptografe um evento ao vivo, criptografe uma mensagem. Conecte o corpo de envio a [`POST /2/chat/conversations/{id}/messages`](/x-api/chat/send-chat-message) como em [Primeiros passos](/pt/xchat/getting-started).

Os snippets usam os dois armazenamentos de sessão **opcionais** para as formas mais curtas de chamada: `set_signing_keys` guarda as chaves públicas dos outros participantes (buscadas do [endpoint de chaves públicas](/x-api/chat/get-user-public-keys)) para que chamadas de descriptografia possam verificar remetentes sem um argumento por chamada, e `set_cache_keys(true)` permite que o SDK lembre a chave verificada de cada conversa, de modo que chamadas de criptografia só precisam do ID da conversa e do texto. Pule qualquer um e passe os mesmos valores por chamada — ambos os estilos verificam de forma idêntica; veja [Descriptografar](#decrypt).

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from chat_xdk import Chat

    chat = Chat(juicebox_config_json)  # or Chat() + import_keys(blob, version)
    chat.unlock("YOUR_PASSCODE")

    # Session defaults: identity for signing, stored signing keys for
    # verification, opt-in cache for conversation keys
    chat.set_identity(my_user_id, signing_key_version)
    chat.set_signing_keys(signing_keys)  # all participants
    chat.set_cache_keys(True)

    # Batch-decrypt the backlog; senders verify against the stored keys
    result = chat.decrypt_events(raw_events)
    for dm in result["messages"]:
        ev = dm["event"]
        if ev["type"] == "Message":
            print(ev["sender_id"], ev["content"]["text"])

    # Decrypt one live event with the cached conversation key
    event = chat.decrypt_event(one_event_b64)

    # Encrypt and sign as the session identity, under the cached key
    payload = chat.encrypt_message(event["conversation_id"], "Hi!")
    message_id = payload.message_id  # SDK-generated — send as message_id
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { createChat } from '@xdevplatform/chat-xdk';

    const chat = await createChat({
      juiceboxConfig: juiceboxConfigJson,
      getAuthToken: async (realmId) => getRealmToken(realmId),
    });
    await chat.unlock('YOUR_PASSCODE');

    // Session defaults: identity for signing, stored signing keys for
    // verification, opt-in cache for conversation keys
    chat.setIdentity(myUserId, signingKeyVersion);
    chat.setSigningKeys(signingKeys); // all participants
    chat.setCacheKeys(true);

    // Batch-decrypt the backlog; senders verify against the stored keys
    const result = chat.decryptEvents(rawEvents);
    for (const dm of result.messages) {
      if (dm.event.type === 'message') {
        console.log(dm.event.senderId, dm.event.content?.text);
      }
    }

    // Decrypt one live event with the cached conversation key
    const event = chat.decryptEvent(oneEventB64);

    // Encrypt and sign as the session identity, under the cached key
    const payload = chat.encryptMessage({ conversationId: event.conversationId!, text: 'Hi!' });
    const messageId = payload.messageId; // SDK-generated — send as message_id
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    // chat_xdk_core::Chat + unlock(b"…").await, or ChatCore + import_keys_with_version

    // Session defaults: identity for signing, stored signing keys for
    // verification, opt-in cache for conversation keys
    chat.set_identity(my_user_id, signing_key_version);
    chat.set_signing_keys(signing_keys); // all participants
    chat.set_cache_keys(true);

    // Batch-decrypt the backlog; senders verify against the stored keys
    let result = chat.decrypt_events(&raw_events, &[]);
    for dm in &result.messages {
        if let Event::Message(msg) = &dm.event {
            println!("{}: {}", msg.meta.sender_id.as_deref().unwrap_or("?"), msg.text().unwrap_or(""));
        }
    }

    // Decrypt one live event with the cached conversation key
    let event = chat.decrypt_event(one_event_b64, &Default::default(), &[])?;

    // Encrypt and sign as the session identity, under the cached key
    let payload = chat.encrypt_message(EncryptMessageParams::new(conversation_id, "Hi!"))?;
    let message_id = payload.message_id; // SDK-generated — send as message_id
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    chat := chatxdk.New()
    defer chat.Close()
    blob, _ := chatxdk.Base64ToBytes(privateKeysB64)
    _ = chat.ImportKeysWithVersion(blob, signingKeyVersion)

    // Session defaults: identity for signing, stored signing keys for
    // verification, opt-in cache for conversation keys
    chat.SetIdentity(myUserID, signingKeyVersion)
    _ = chat.SetSigningKeys(signingKeys) // all participants
    chat.SetCacheKeys(true)

    // Batch-decrypt the backlog; senders verify against the stored keys
    result, err := chat.DecryptEvents(rawEvents, nil)
    for _, dm := range result.Messages {
        if dm.Event.Type == "Message" {
            fmt.Println(dm.Event.AsMessage().Text())
        }
    }

    // Decrypt one live event with the cached conversation key
    event, err := chat.DecryptEvent(oneEventB64, nil, nil)
    msg := event.AsMessage() // nil unless event.Type == "Message"

    // Encrypt and sign as the session identity, under the cached key
    payload, err := chat.EncryptMessage(chatxdk.EncryptMessageParams{
        ConversationID: *msg.ConversationID,
        Text:           "Hi!",
    })
    messageID := payload.MessageID // SDK-generated — send as message_id
    _ = messageID
    _ = err
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    using var chat = new Chat();
    chat.ImportKeys(privateKeyBytes, signingKeyVersion);

    // Session defaults: identity for signing, stored signing keys for
    // verification, opt-in cache for conversation keys
    chat.SetIdentity(myUserId, signingKeyVersion);
    chat.SetSigningKeys(signingKeys); // all participants
    chat.SetCacheKeys(true);

    // Batch-decrypt the backlog; senders verify against the stored keys
    var result = chat.DecryptEvents(rawEvents);
    foreach (var dm in result.Messages)
    {
        if (dm.Event.GetProperty("type").GetString() == "Message")
            Console.WriteLine(dm.Event.GetProperty("content").GetProperty("text").GetString());
    }

    // Decrypt one live event with the cached conversation key
    var evt = chat.DecryptEvent(oneEventB64);
    var conversationId = evt.GetProperty("conversation_id").GetString()!;

    // Encrypt and sign as the session identity, under the cached key
    var payload = chat.EncryptMessage(new EncryptMessageParams(conversationId, "Hi!"));
    var messageId = payload.MessageId; // SDK-generated — send as message_id
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    try (Chat chat = new Chat()) {
        chat.importKeys(privateKeyBytes, signingKeyVersion);

        // Session defaults: identity for signing, stored signing keys for
        // verification, opt-in cache for conversation keys
        chat.setIdentity(myUserId, signingKeyVersion);
        chat.setSigningKeys(signingKeys); // all participants
        chat.setCacheKeys(true);

        // Batch-decrypt the backlog; senders verify against the stored keys
        DecryptEventsResult result = chat.decryptEvents(rawEvents, null);
        for (DecryptedMessage dm : result.messages) {
            if ("Message".equals(dm.event.path("type").asText())) {
                System.out.println(dm.event.path("content").path("text").asText());
            }
        }

        // Decrypt one live event with the cached conversation key
        JsonNode event = chat.decryptEvent(oneEventB64, (Map<String, byte[]>) null, null);
        String conversationId = event.path("conversation_id").asText();

        // Encrypt and sign as the session identity, under the cached key
        SendPayload payload = chat.encryptMessage(new EncryptMessageParams(conversationId, "Hi!"));
        String messageId = payload.messageId; // SDK-generated — send as message_id
    }
    ```
  </Tab>
</Tabs>

***

## Ciclo de vida e chaves

Construa o SDK, armazene chaves privadas (backup seguro de chave protegido por código de acesso ou um blob de chave local), registre as chaves **públicas** com a Chat API e chame **`set_identity(user_id, signing_key_version)`** após o unlock ou o import — isso define o remetente e a versão de chave de assinatura padrão de cada ação assinada, para que os métodos de criptografia e preparação funcionem sem argumentos de identidade por chamada. Chame `generate_keypairs` uma vez por identidade de dispositivo/app; poste o payload de registro no endpoint de chaves públicas. Use `setup` / `unlock` (e os helpers de código de acesso relacionados) para backup seguro de chave em cada binding. `export_keys` / `import_keys` (persistência de blob de chave em bruto para bots e servidores) estão disponíveis **apenas nos bindings nativos** — Python, Go, .NET, JVM e Rust. O binding JS/WASM não expõe exportação ou importação de chave em bruto: em um navegador, qualquer script que alcance a instância pode exfiltrar a identidade, então o JS mantém as chaves dentro do backup seguro de chave. Um servidor JS que queira evitar uma viagem ao realm de backup por requisição deve reutilizar uma instância `Chat` desbloqueada entre requisições, ou executar um binding nativo onde blobs de chave são suportados.

O SDK também precisa da versão que a API do X reporta para sua chave pública registrada, para que entradas de mudança de chave direcionadas a outras versões sejam ignoradas. `set_identity` a registra junto com o ID de usuário; `import_keys` a aceita diretamente como um argumento opcional (Rust e Go usam `import_keys_with_version` / `ImportKeysWithVersion`).

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from chat_xdk import Chat

    # Secure key backup (client)
    chat = Chat(juicebox_config_json)
    chat.setup("YOUR_PASSCODE")          # first time — generates keypairs
    # chat.unlock("YOUR_PASSCODE")        # later sessions
    chat.set_identity(user_id, version)  # version from add-public-key / get-public-keys response
    reg = chat.get_public_keys()     # or registration fields from generate_keypairs

    # Key blob (server / bot)
    chat2 = Chat()
    chat2.import_keys(secret_blob, version)
    chat2.set_identity(user_id, version)
    blob = chat2.export_keys()       # treat as a password
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { createChat } from '@xdevplatform/chat-xdk';

    const chat = await createChat({
      juiceboxConfig: juiceboxConfigJson,
      getAuthToken: async (realmId) => getRealmToken(realmId),
    });
    await chat.setup('YOUR_PASSCODE');
    // await chat.unlock('YOUR_PASSCODE');
    chat.setIdentity(userId, version);
    const publics = chat.getPublicKeys();

    // JS/WASM stores keys only through secure key backup — there is no raw key
    // export/import here. For key-blob persistence, use a native binding.
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    // chat_xdk_core::Chat — async secure key backup unlock, or ChatCore + import_keys
    chat.setup(b"YOUR_PASSCODE").await?;
    // chat.unlock(b"YOUR_PASSCODE").await?;
    chat.set_identity(user_id, version);
    let publics = chat.get_public_keys()?;
    let blob = chat.export_keys()?;
    chat.import_keys_with_version(&blob, version)?;
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    chat := chatxdk.New()
    defer chat.Close()

    // Prefer ImportKeys for servers; secure key backup unlock where supported
    keyBlob, _ := chatxdk.Base64ToBytes(privateKeysB64)
    if err := chat.ImportKeysWithVersion(keyBlob, version); err != nil {
        log.Fatal(err)
    }
    chat.SetIdentity(userID, version)
    publics, err := chat.GetPublicKeys()
    blob, err := chat.ExportKeys()
    _ = publics
    _ = blob
    _ = err
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    using var chat = new Chat();
    chat.ImportKeys(privateKeyBytes, version);
    // or secure key backup setup / unlock when config is available
    chat.SetIdentity(userId, version);
    var publics = chat.GetPublicKeys();
    var blob = chat.ExportKeys();
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    try (Chat chat = new Chat()) {
        chat.importKeys(privateKeyBytes, version);
        chat.setIdentity(userId, version);
        var publics = chat.getPublicKeys();
        byte[] blob = chat.exportKeys();
    }
    ```
  </Tab>
</Tabs>

A configuração do backup seguro de chave aceita três formatos: o objeto `juicebox_config` da API do X (recomendado — passado literalmente), um wrapper completo `sdk_config` ou um `token_map` puro.

Opcional: a verificação de assinatura está **ligada por padrão** (`reject_unverified = true`) — chame `set_reject_unverified(false)` para desabilitá-la (não recomendado); `update_config` se a configuração do realm de backup mudar; `is_unlocked` / `has_identity_key` para estado de UI. As listas completas de campos estão nos stubs do [repositório chat-xdk](https://github.com/xdevplatform/chat-xdk).

***

## Chaves de conversa

Três métodos **prepare**, cada um faz com que uma chamada realize tudo o que uma mudança de chave precisa: gerar uma nova chave de conversa, criptografá-la para cada participante (a partir das chaves públicas que você passa) e assinar a mudança. A identidade do remetente e a versão de chave de assinatura vêm da sessão (`set_identity`); defina `sender_id` / `signing_key_version` nos parâmetros para sobrescrever. Todos retornam o mesmo formato **`PreparedConversationChange`**, pronto para POST — renomeie o campo do SDK `encrypted_key` para **`encrypted_conversation_key`** em `conversation_participant_keys` e mapeie as assinaturas de ação para o campo obrigatório **`action_signatures`** do corpo.

| Cenário                                                                                                          | Método                            | Assinaturas de ação retornadas |
| :--------------------------------------------------------------------------------------------------------------- | :-------------------------------- | :----------------------------- |
| Iniciar um 1:1 (omita o ID de conversa — o SDK o deriva) ou rotacionar a chave de qualquer conversa (passe o ID) | `prepare_conversation_key_change` | 1                              |
| Criar um grupo (ID gerado por `POST /2/chat/conversations/group/initialize`)                                     | `prepare_group_create`            | 2 — envie ambas                |
| Adicionar membros a um grupo                                                                                     | `prepare_group_members_change`    | 2 — envie ambas                |

Guarde os bytes da chave em **bruto** para `encrypt_message` e mídia; nunca passe o envelope criptografado da API para a criptografia.

<Warning>
  **Verifique as chaves obtidas antes de empacotar.** Os métodos prepare criptografam a nova chave da conversa para quaisquer chaves públicas que você passar. Antes de passá-las, chame `verify_key_binding(identity, signing, signature)` em cada registro obtido — seus campos `public_key`, `signing_public_key` e `identity_public_key_signature` da API de chaves públicas — para que uma chave de identidade substituída não possa receber a chave da conversa.
</Warning>

Use `extract_conversation_keys` em payloads de eventos de mudança de chave para reconstruir `{ keys, latest_version }`. `decrypt_conversation_key` desempacota um único blob ECIES.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    # One entry per participant public key, from the public-keys API:
    # participants = [
    #     {"user_id": "1215441834412953600", "public_key": "BASE64_IDENTITY_PUBLIC_KEY", "key_version": "1733889755256"},
    #     {"user_id": "1843439638876491776", "public_key": "BASE64_IDENTITY_PUBLIC_KEY", "key_version": "1766181805686"},
    # ]
    prepared = chat.prepare_conversation_key_change(participants)
    # prepared["conversation_key"]   — raw bytes for encrypt_message
    # prepared["participant_keys"]   — per-user wraps; rename encrypted_key → encrypted_conversation_key on POST
    # prepared["action_signatures"]  — required on the POST body

    extracted = chat.extract_conversation_keys(key_change_blobs)
    keys = extracted["keys"]
    latest = extracted["latest_version"]
    raw = keys[latest]

    one = chat.decrypt_conversation_key(encrypted_blob)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const prepared = chat.prepareConversationKeyChange({ publicKeys: participants });
    // prepared.conversationKey — Uint8Array for encryptMessage
    // prepared.participantKeys / prepared.actionSignatures — POST body fields

    const extracted = chat.extractConversationKeys(keyChangeBlobs);
    const raw = extracted.keys[extracted.latestVersion!];

    const one = chat.decryptConversationKey(encryptedBlob);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    let prepared = chat.prepare_conversation_key_change(
        ConversationKeyChangeParams::new(participants),
    )?;
    let extracted = chat.extract_conversation_keys(&key_change_blobs);
    let latest = extracted.latest_version.as_deref().unwrap_or_default();
    let raw = &extracted.keys[latest];
    let one = chat.decrypt_conversation_key(&encrypted_blob)?;
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    prepared, err := chat.PrepareConversationKeyChange(chatxdk.ConversationKeyChangeParams{
        PublicKeys: participants,
    })
    // prepared.ConversationKey feeds EncryptMessage
    // prepared.ParticipantKeys / prepared.ActionSignatures — POST body fields
    extracted, err := chat.ExtractConversationKeys(keyChangeBlobs)
    one, err := chat.DecryptConversationKey(encryptedBlob)
    _ = prepared
    _ = extracted
    _ = one
    _ = err
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    var prepared = chat.PrepareConversationKeyChange(new ConversationKeyChangeParams(participants));
    var extracted = chat.ExtractConversationKeys(keyChangeBlobs);
    var raw = extracted.Keys[extracted.LatestVersion];
    var one = chat.DecryptConversationKey(encryptedBlob);
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    PreparedConversationChange prepared =
            chat.prepareConversationKeyChange(new ConversationKeyChangeParams(participants));
    ConversationKeyBundle extracted = chat.extractConversationKeys(keyChangeBlobs);
    byte[] raw = extracted.keys.get(extracted.latestVersion);
    byte[] one = chat.decryptConversationKey(encryptedBlob);
    ```
  </Tab>
</Tabs>

Para criação de grupo e adição de membros, passe os parâmetros que cada método precisa (listas de IDs de membros/administradores para `prepare_group_create`; nova + composição atual para `prepare_group_members_change`) — veja [Grupos](/pt/xchat/groups#create-the-group-and-establish-keys) para exemplos. Ambos retornam **duas** assinaturas de ação; o POST deve incluir as duas.

***

## Descriptografar

**`decrypt_events`** é para histórico e backlog: extrai as chaves de conversa do fluxo, retorna mensagens descriptografadas e **coleta** erros por evento em vez de falhar o lote inteiro. **`decrypt_event`** é para um único evento ao vivo; lança/aciona exceção em caso de falha.

Passe **chaves de assinatura** para que o SDK possa verificar remetentes. Mapeie os campos da API de chaves públicas para `SigningKeyEntry`: `public_key_version` → `public_key_version` (mesmo nome), `signing_public_key` → `public_key`, `public_key` → `identity_public_key`, mais `identity_public_key_signature` e `user_id`.

Dois armazenamentos de sessão opcionais permitem omitir os argumentos de chave por chamada:

* **`set_signing_keys(entries)`** armazena as chaves de assinatura dos participantes; uma chamada de descriptografia que omita (ou passe vazio) o argumento de chaves de assinatura usa o armazenamento no lugar. A verificação em si permanece inalterada — chaves entram no armazenamento apenas por essa chamada, nunca a partir dos eventos que estão sendo descriptografados. Cada chamada substitui o conjunto anterior.
* **`set_cache_keys(true)`** habilita o cache de chave de conversa (desligado por padrão). Enquanto habilitado, `decrypt_events` faz cache, por conversa, da chave mais recente cuja mudança de chave tinha uma assinatura válida; `decrypt_event` recorre a ela quando seu argumento de chaves de conversa é omitido, e os helpers de criptografia resolvem uma chave de conversa omitida a partir dele. Desabilitar limpa o cache.

Um argumento explícito e não vazio sempre prevalece sobre os armazenamentos. Argumentos explícitos por chamada continuam sendo cidadãos de primeira classe — e são a escolha certa para deployments serverless ou multi-instância, onde uma requisição pode cair em uma instância nova cujos armazenamentos estão vazios.

A verificação é obrigatória por padrão: omitir chaves de assinatura nunca a pula. Sem nada passado e nada armazenado, eventos assinados falham (coletados em `errors` para `decrypt_events`, lançados para `decrypt_event`). Para de fato pular a verificação, você deve primeiro chamar `set_reject_unverified(false)` (não recomendado em produção).

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    signing_keys = [{
        "user_id": uid,
        "public_key_version": row["public_key_version"],
        "public_key": row["signing_public_key"],
        "identity_public_key": row["public_key"],
        "identity_public_key_signature": row["identity_public_key_signature"],
    } for row in api_public_keys]

    result = chat.decrypt_events(raw_events, signing_keys)
    for idx, msg in (result.get("errors") or {}).items():
        log.warning("event %s failed: %s", idx, msg)
    for dm in result["messages"]:
        ev = dm["event"]
        if ev["type"] == "Message":
            text = ev["content"].get("text")

    cached = result["conversation_keys"]["keys"]
    live = chat.decrypt_event(one_event_b64, cached, signing_keys)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const signingKeys = apiPublicKeys.map((row) => ({
      userId: uid,
      publicKeyVersion: row.public_key_version,
      publicKey: row.signing_public_key,
      identityPublicKey: row.public_key,
      identityPublicKeySignature: row.identity_public_key_signature,
    }));

    const result = chat.decryptEvents(rawEvents, signingKeys);
    for (const [idx, msg] of Object.entries(result.errors ?? {})) {
      console.warn(`event ${idx} failed: ${msg}`);
    }
    const cached = result.conversationKeys.keys;
    const live = chat.decryptEvent(oneEventB64, cached, signingKeys);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    let result = chat.decrypt_events(&raw_events, &signing_keys);
    for (idx, msg) in &result.errors {
        eprintln!("event {idx} failed: {msg}");
    }
    let cached = &result.conversation_keys.keys;
    let live = chat.decrypt_event(one_event_b64, cached, &signing_keys)?;
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    result, err := chat.DecryptEvents(rawEvents, signingKeys)
    for idx, msg := range result.Errors {
        log.Printf("event %s failed: %s", idx, msg)
    }
    cached := result.ConversationKeys.Keys
    live, err := chat.DecryptEvent(oneEventB64, cached, signingKeys)
    _ = live
    _ = err
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    var result = chat.DecryptEvents(rawEvents, signingKeys);
    foreach (var kv in result.Errors) { /* kv.Key = event index, kv.Value = error */ }
    var cached = result.ConversationKeys.Keys;
    var live = chat.DecryptEvent(oneEventB64, cached, signingKeys);
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    DecryptEventsResult result = chat.decryptEvents(rawEvents, signingKeys);
    Map<String, byte[]> cached = result.conversationKeys.keys;
    JsonNode live = chat.decryptEvent(oneEventB64, cached, signingKeys);
    ```
  </Tab>
</Tabs>

***

## Helpers de criptografia e envio

**`encrypt_message(conversation_id, text)`** monta o texto cifrado assinado para uma mensagem de texto; opcionais `entities`, `attachments` (via `media_hash_key`), `should_notify` e `ttl_msec`. A identidade do remetente é resolvida a partir da sessão (`set_identity`) e a chave da conversa, a partir do cache opcional de chaves (`set_cache_keys`) — ou passe `sender_id` / `signing_key_version` e `conversation_key` + `conversation_key_version` explicitamente. O SDK gera o **`message_id`** (um UUID incorporado no evento assinado) e o retorna no payload — nunca crie o seu próprio; reutilize o mesmo payload em retentativas para que um ID nunca seja gerado duas vezes. Mapeie o payload para o corpo send-message: `message_id` → **`message_id`**, `encrypted_content` → **`encoded_message_create_event`**, `encoded_event_signature` → **`encoded_message_event_signature`**.

**Respostas são baseadas em eventos.** `encrypt_reply(conversation_id, text, reply_to_event)` recebe o evento em bruto codificado em base64 sendo respondido. O SDK deriva o preview citado (sequence id, remetente, texto, entidades, anexos) a partir dele e incorpora o original assinado na mensagem enviada para que os destinatários possam validar a citação. Passe `reply_to_ckces` — os eventos brutos de mudança de chave — quando o original foi criptografado em uma versão de chave mais antiga que a resposta. Quando o original foi **editado**, passe o evento de edição em bruto como `reply_to_edit_event`: o preview então cita o que a mensagem diz agora (seu texto e entidades vêm da edição), e a edição viaja junto com o original para o destinatário verificar. Os campos explícitos `reply_to_*` permanecem como overrides para callers que não têm mais o evento em bruto.

**Reações também são baseadas em eventos.** `encrypt_add_reaction(target_event, emoji)` e `encrypt_remove_reaction(...)` derivam o ID da conversa e o sequence id alvo a partir do evento em bruto sendo reagido; os mesmos parâmetros podem adicionar e depois remover uma reação. Defina `conversation_id` e `target_message_sequence_id` explicitamente apenas quando você não tiver mais o evento em bruto.

No lado do recebimento, uma mensagem descriptografada que cita uma resposta traz **`reply_preview_validation`** (`"Valid"` / `"Invalid"`; o binding JS usa `'valid'` / `'invalid'`): o SDK verificou a assinatura do original incorporado contra suas chaves de assinatura — nunca contra uma chave carregada no evento — descriptografou-o e comparou o conteúdo citado e o autor com ele. Quando o preview incorpora um evento de edição, o SDK verifica a edição da mesma forma (mesma conversa, mesmo autor do original) e confere o texto citado contra o conteúdo editado, em vez do texto pré-edição. O campo está ausente quando a mensagem não traz preview ou o preview não incorpora um original. Trate previews `Invalid` como não confiáveis: a mensagem em si é autêntica, mas o material citado não é — renderize as citações apenas a partir do original validado.

**`encrypt` / `decrypt`** são para metadados UTF-8 sob a chave da conversa (por exemplo, um nome de grupo criptografado) — não envelopes de mensagem. **`encrypt_stream` / `decrypt_stream`** criptografam bytes de anexo; veja [Mídia](/pt/xchat/media). Os **`sign` / `verify` / `verify_key_binding`** de baixo nível dão suporte a fluxos avançados; mudanças de chave de conversa, criações de grupo e adições de membros são assinadas pelos [métodos prepare](#conversation-keys).

O ID de conversa passado para `encrypt_message` / `encrypt_reply` pode ser qualquer forma que você tenha — `A:B` de eventos, `A-B` de listagens ou caminhos de URL (em qualquer ordem), ou o ID de usuário do destinatário puro — o SDK o canoniza antes de assinar. IDs de grupo (com prefixo `g`) passam sem alteração.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    payload = chat.encrypt_message(
        conversation_id, "Hello",
        # Optional keyword args: entities, attachments, should_notify, ttl_msec
    )
    body = {
        "message_id": payload.message_id,
        "encoded_message_create_event": payload.encrypted_content,
        "encoded_message_event_signature": payload.encoded_event_signature,
    }
    # POST body to /2/chat/conversations/{id}/messages

    # Preview derived from + embedded raw event so recipients can validate;
    # add reply_to_ckces=[...] when the original used an older key version
    reply = chat.encrypt_reply(conversation_id, "Sounds good", original_event_b64)

    # Conversation and target derived from the raw event
    add = chat.encrypt_add_reaction(original_event_b64, "👍")
    remove = chat.encrypt_remove_reaction(original_event_b64, "👍")

    name_ct = chat.encrypt("Group title", raw_conversation_key)
    title = chat.decrypt(name_ct, raw_conversation_key)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const payload = chat.encryptMessage({
      conversationId,
      text: 'Hello',
      // Optional: entities, attachments, shouldNotify, ttlMsec
    });
    const body = {
      message_id: payload.messageId,
      encoded_message_create_event: payload.encryptedContent,
      encoded_message_event_signature: payload.encodedEventSignature,
    };
    // POST body to /2/chat/conversations/{id}/messages

    // Preview derived from + embedded raw event so recipients can validate;
    // add replyToCkces: [...] when the original used an older key version
    const reply = chat.encryptReply({
      conversationId,
      text: 'Sounds good',
      replyToEvent: originalEventB64,
    });

    // Conversation and target derived from the raw event
    const add = chat.encryptAddReaction({ emoji: '👍', targetEvent: originalEventB64 });
    const remove = chat.encryptRemoveReaction({ emoji: '👍', targetEvent: originalEventB64 });

    const nameCt = chat.encrypt('Group title', rawConversationKey);
    const title = chat.decrypt(nameCt, rawConversationKey);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    let payload = chat.encrypt_message(EncryptMessageParams::new(conversation_id, "Hello"))?;
    // Send body: payload.message_id → message_id,
    // payload.encrypted_content → encoded_message_create_event,
    // payload.encoded_event_signature → encoded_message_event_signature

    // Preview derived from + embedded raw event so recipients can validate;
    // set params.reply_to_ckces when the original used an older key version
    let reply = chat.encrypt_reply(EncryptReplyParams::new(
        conversation_id, "Sounds good", original_event_b64,
    ))?;

    // Conversation and target derived from the raw event
    let reaction = EncryptReactionParams::new(original_event_b64, "👍");
    let add = chat.encrypt_add_reaction(&reaction)?;
    let remove = chat.encrypt_remove_reaction(&reaction)?;

    // conv_key: XChatConversationKey from extract_conversation_keys / decrypt_conversation_key
    let name_ct = chat.encrypt("Group title", &conv_key)?;
    let title = chat.decrypt(&name_ct, &conv_key)?;
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    payload, err := chat.EncryptMessage(chatxdk.EncryptMessageParams{
        ConversationID: conversationID,
        Text:           "Hello",
    })
    // Send body: payload.MessageID → message_id,
    // payload.EncryptedContent → encoded_message_create_event,
    // payload.EncodedEventSignature → encoded_message_event_signature

    // Preview derived from + embedded raw event so recipients can validate;
    // set ReplyToCkces when the original used an older key version
    reply, err := chat.EncryptReply(chatxdk.EncryptReplyParams{
        ConversationID: conversationID,
        Text:           "Sounds good",
        ReplyToEvent:   originalEventB64,
    })

    // Conversation and target derived from the raw event
    reaction := chatxdk.EncryptReactionParams{Emoji: "👍", TargetEvent: originalEventB64}
    add, err := chat.EncryptAddReaction(reaction)
    remove, err := chat.EncryptRemoveReaction(reaction)

    nameCt, err := chat.Encrypt("Group title", rawKey)
    title, err := chat.Decrypt(nameCt, rawKey)
    _ = payload
    _ = reply
    _ = add
    _ = remove
    _ = title
    _ = err
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    var payload = chat.EncryptMessage(new EncryptMessageParams(conversationId, "Hello"));
    // Send body: payload.MessageId → message_id,
    // payload.EncryptedContent → encoded_message_create_event,
    // payload.EncodedEventSignature → encoded_message_event_signature

    // Preview derived from + embedded raw event so recipients can validate;
    // set ReplyToCkces when the original used an older key version
    var reply = chat.EncryptReply(new EncryptReplyParams(conversationId, "Sounds good", originalEventB64));

    // Conversation and target derived from the raw event
    var reaction = new EncryptReactionParams(originalEventB64, "👍");
    var add = chat.EncryptAddReaction(reaction);
    var remove = chat.EncryptRemoveReaction(reaction);

    var nameCt = chat.Encrypt("Group title", rawKey);
    var title = chat.Decrypt(nameCt, rawKey);
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    SendPayload payload = chat.encryptMessage(new EncryptMessageParams(conversationId, "Hello"));
    // Send body: payload.messageId → message_id,
    // payload.encryptedContent → encoded_message_create_event,
    // payload.encodedEventSignature → encoded_message_event_signature

    // Preview derived from + embedded raw event so recipients can validate;
    // set replyToCkces when the original used an older key version
    SendPayload reply =
            chat.encryptReply(new EncryptReplyParams(conversationId, "Sounds good", originalEventB64));

    // Conversation and target derived from the raw event
    EncryptReactionParams reaction = new EncryptReactionParams(originalEventB64, "👍");
    SendPayload add = chat.encryptAddReaction(reaction);
    SendPayload remove = chat.encryptRemoveReaction(reaction);

    String nameCt = chat.encrypt("Group title", rawKey);
    String title = chat.decrypt(nameCt, rawKey);
    ```
  </Tab>
</Tabs>

***

## Streams de mídia

Criptografe os bytes de arquivo com a **mesma** chave de conversa usada para texto, faça upload pelas APIs de mídia de Chat e anexe **`media_hash_key`** em `encrypt_message`. Isso não é o modelo de mídia de Posts (`expansions=attachments.media_keys`). Fluxo completo de upload/download: [Mídia](/pt/xchat/media).

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    ciphertext = chat.encrypt_stream(file_bytes, raw_conversation_key)
    # Upload `ciphertext`; the `media_hash_key` you attach on encrypt_message
    # comes from the media-upload finalize step, not from encrypt_stream.

    plain = chat.decrypt_stream(ciphertext, raw_conversation_key)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const ciphertext = chat.encryptStream(fileBytes, rawConversationKey);
    // Upload `ciphertext`; mediaHashKey comes from the upload finalize step.
    const plain = chat.decryptStream(ciphertext, rawConversationKey);
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    // conv_key: &XChatConversationKey from extract_conversation_keys / decrypt_conversation_key
    let ciphertext = chat.encrypt_stream(&file_bytes, &conv_key)?;
    let plain = chat.decrypt_stream(&ciphertext, &conv_key)?;
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    ciphertext, err := chat.EncryptStream(fileBytes, rawKey)
    plain, err := chat.DecryptStream(ciphertext, rawKey)
    _ = plain
    _ = err
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    var ciphertext = chat.EncryptStream(fileBytes, rawKey);
    var plain = chat.DecryptStream(ciphertext, rawKey);
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    byte[] ciphertext = chat.encryptStream(fileBytes, rawKey);
    byte[] plain = chat.decryptStream(ciphertext, rawKey);
    ```
  </Tab>
</Tabs>

### Streaming incremental para mídia grande

Para arquivos grandes, evite manter o payload inteiro em memória: `stream_encryptor()` / `stream_decryptor()` retornam um `StreamEncryptor` / `StreamDecryptor` que você alimenta em chunks (cerca de 1 MB cada) com `push(chunk)` e depois chama `finish()` uma vez ao final. Na descriptografia, `finish()` detecta um stream truncado (falha se a entrada terminou antes do frame final), então não trate o texto simples empurrado como completo até que ele seja bem-sucedido.

<Warning>
  **Apenas JS/WASM:** `finish()` consome e libera o objeto WASM subjacente — nunca chame `free()` depois de `finish()` (lança erro). Chame `free()` apenas para abandonar um stream *antes* de finalizar (por exemplo, em um caminho de erro).
</Warning>

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    enc = chat.stream_encryptor(raw_conversation_key)
    chunks = [enc.push(chunk) for chunk in read_in_chunks(file_bytes, 1 << 20)]
    chunks.append(enc.finish())
    ciphertext = b"".join(chunks)

    dec = chat.stream_decryptor(raw_conversation_key)
    out = [dec.push(chunk) for chunk in read_in_chunks(ciphertext, 1 << 20)]
    out.append(dec.finish())  # raises on truncation
    plain = b"".join(out)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    const enc = chat.streamEncryptor(rawConversationKey);
    const parts: Uint8Array[] = [];
    try {
      for (const chunk of readInChunks(fileBytes, 1 << 20)) parts.push(enc.push(chunk));
      parts.push(enc.finish()); // consumes + frees enc — do not call enc.free() after this
    } catch (e) {
      enc.free(); // only when abandoning before finish()
      throw e;
    }
    const ciphertext = concat(parts);
    ```
  </Tab>
</Tabs>

***

## Utilitários

Helpers de base64/hex, detecção de MIME e dimensões de imagem estão disponíveis como funções em nível de módulo (Python/JS/Rust/Go) ou `ChatXdkUtilities` (C#/Java) — úteis ao construir metadados de anexo sem trazer bibliotecas extras.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    from chat_xdk import (
        bytes_to_base64, base64_to_bytes, bytes_to_hex, hex_to_bytes,
        detect_mime_type, detect_image_dimensions,
    )

    b64 = bytes_to_base64(raw)
    raw2 = base64_to_bytes(b64)
    hexed = bytes_to_hex(raw)
    raw3 = hex_to_bytes(hexed)
    mime = detect_mime_type(file_bytes)
    w, h = detect_image_dimensions(file_bytes)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    import { bytesToBase64, base64ToBytes, bytesToHex, hexToBytes, detectMimeType, detectImageDimensions } from '@xdevplatform/chat-xdk';

    const b64 = bytesToBase64(raw);
    const raw2 = base64ToBytes(b64);
    const hexed = bytesToHex(raw);
    const raw3 = hexToBytes(hexed);
    const mime = detectMimeType(fileBytes);
    const dims = detectImageDimensions(fileBytes);
    const width = dims?.width ?? 0;
    const height = dims?.height ?? 0;
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    let b64 = chat_xdk_core::bytes_to_base64(&raw);
    let raw2 = chat_xdk_core::base64_to_bytes(&b64)?;
    let hexed = chat_xdk_core::bytes_to_hex(&raw);
    let raw3 = chat_xdk_core::hex_to_bytes(&hexed);
    let mime = chat_xdk_core::detect_mime_type(&file_bytes);
    let dims = chat_xdk_core::detect_image_dimensions(&file_bytes);
    let (w, h) = dims.map(|d| (d.width, d.height)).unwrap_or((0, 0));
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    b64, _ := chatxdk.BytesToBase64(raw)
    raw2, err := chatxdk.Base64ToBytes(b64)
    hexed, err := chatxdk.BytesToHex(raw)
    raw3, err := chatxdk.HexToBytes(hexed)
    mime, _ := chatxdk.DetectMimeType(fileBytes)
    dims, _ := chatxdk.DetectImageDimensions(fileBytes)
    w, h := dims.Width, dims.Height
    _ = b64
    _ = raw2
    _ = hexed
    _ = raw3
    _ = mime
    _ = w
    _ = h
    _ = err
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    var b64 = ChatXdkUtilities.BytesToBase64(raw);
    var raw2 = ChatXdkUtilities.Base64ToBytes(b64);
    var hexed = ChatXdkUtilities.BytesToHex(raw);
    var raw3 = ChatXdkUtilities.HexToBytes(hexed);
    var mime = ChatXdkUtilities.DetectMimeType(fileBytes);
    var dims = ChatXdkUtilities.DetectImageDimensions(fileBytes);
    var w = dims?.Width ?? 0;
    var h = dims?.Height ?? 0;
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    String b64 = ChatXdkUtilities.bytesToBase64(raw);
    byte[] raw2 = ChatXdkUtilities.base64ToBytes(b64);
    String hexed = ChatXdkUtilities.bytesToHex(raw);
    byte[] raw3 = ChatXdkUtilities.hexToBytes(hexed);
    String mime = ChatXdkUtilities.detectMimeType(fileBytes);
    ImageDimensions wh = ChatXdkUtilities.detectImageDimensions(fileBytes);
    long width = wh.width, height = wh.height;
    ```
  </Tab>
</Tabs>

***

## Tipos importantes

Estes tipos conceituais aparecem em todas as linguagens (os nomes exatos dos campos diferem; JS frequentemente usa discriminadores de evento em camelCase como `message`):

* **SendPayload** — valor de retorno de `encrypt_message` e dos outros helpers de criptografia: o **`message_id`** gerado pelo SDK (um UUID incorporado no evento assinado — envie-o como `message_id` da mensagem e guarde-o para deduplicação), `encrypted_content`, `encoded_event_signature`, metadados da assinatura, `conversation_key_version` e `should_notify`. Mapeie para o corpo de envio da Chat API.
* **PublicKeyRegistrationPayload** — saída de `generate_keypairs` / getters de chave pública para a API add-public-key.
* **SigningKeyEntry** — material público do remetente passado para descriptografia para verificação de assinatura, ou armazenado via `set_signing_keys`.
* **PreparedConversationChange** — saída dos três métodos prepare: o `conversation_id` derivado ou passado, os bytes brutos de `conversation_key`, `conversation_key_version`, `participant_keys` (`user_id`, `encrypted_key`, `public_key_version`) e `action_signatures` (`message_id`, `encoded_message_event_detail`, `signature`, `signature_version`, `public_key_version`, opcional `signature_payload` — omitido em assinaturas de mudança de chave porque esse payload incorpora a chave em texto claro).
* **DecryptEventsResult** — mensagens, erros opcionais e `conversation_keys` extraídas. Mensagens descriptografadas que citam uma resposta trazem `reply_preview_validation` (veja [Helpers de criptografia e envio](#encrypt-and-send-helpers)).

Para listas completas de campos, use os stubs de linguagem no [repositório chat-xdk](https://github.com/xdevplatform/chat-xdk) (`docs/API.md`, `*.pyi`, `index.d.ts`).

***

## Erros

Python normalmente lança **`ValueError`** com uma mensagem descritiva (por exemplo, um código de acesso inválido). TypeScript/JavaScript lança **`Error`**. Go retorna `(value, error)`. Prefira **`decrypt_events`** para histórico, para que um evento ruim não aborte o lote; inspecione a coleção de erros para falhas parciais.

Alguns erros de verificação são **permanentes**. Assinaturas são imutáveis e verificadas reconstruindo o payload assinado a partir do próprio evento, então um evento antigo que falha com `signature missing or no matching signing key` ou com um mismatch de ECDSA falhará em toda carga futura — nenhuma retentativa, atualização de chave ou chamada de API pode consertá-lo. Trate esses casos como tombstones, não como erros transitórios. Rotacionar a chave da conversa inicia um histórico limpo e verificável a partir desse ponto.

***

## Próximos passos

<CardGroup cols={2}>
  <Card title="Primeiros passos" icon="rocket" href="/pt/xchat/getting-started">
    Conecte o Chat XDK à Chat API
  </Card>

  <Card title="Mídia" icon="image" href="/pt/xchat/media">
    Criptografia em stream e REST de mídia
  </Card>

  <Card title="Eventos em tempo real" icon="bolt" href="/pt/xchat/real-time-events">
    Entrega via webhooks e activity
  </Card>

  <Card title="Solução de problemas" icon="wrench" href="/pt/xchat/troubleshooting">
    Falhas comuns
  </Card>
</CardGroup>