Chat XDK Reference

The Chat XDK handles key management, encryption, decryption, and signing for X Chat. It does not call the X HTTP API—pair it with the Python or TypeScript XDK, or with HTTPS and a user access token. App walkthrough: Getting Started. Sample bots: chat-xdk/examples.

Install

pip install chat-xdk

npm install @xdevplatform/chat-xdk

[dependencies]
chat-xdk-core = "0.2"
# or: chat_xdk for the async Juicebox-oriented crate

go get github.com/xdevplatform/chat-xdk/go/chatxdk

# From the chat-xdk repo: cargo build -p chat-xdk-dotnet --release
# Reference the ChatXdk package; place the native library on the loader path (.NET 8+)

# Use com.xdevplatform.chatxdk (JNA) and the same native library as .NET (JDK 17+)
# Set jna.library.path to the built chat_xdk_dotnet library

Quick start

Decrypt a backlog, cache keys, decrypt one event, encrypt a reply. Wire the send body to POST /2/chat/conversations/{id}/messages as in Getting Started.

from chat_xdk import Chat

chat = Chat(juicebox_config_json)  # or Chat() + import_keys(blob)
chat.unlock("YOUR_PIN")
chat.set_key_version(signing_key_version)

result = chat.decrypt_events(raw_events, signing_keys)
for dm in result["messages"]:
    ev = dm["event"]
    if ev.get("type") == "Message":
        print(ev.get("sender_id"), ev.get("content", {}).get("text"))

cached = result["conversation_keys"]["keys"]
event = chat.decrypt_event(one_event_b64, cached, sender_signing_keys)

raw_key = cached[result["conversation_keys"]["latest_version"]]
payload = chat.encrypt_message(
    message_id, sender_id, conversation_id, raw_key, "Hi!",
    conversation_key_version, signing_key_version,
)

import { createChat } from '@xdevplatform/chat-xdk';

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

const result = chat.decryptEvents(rawEvents, signingKeys);
for (const dm of result.messages) {
  if (dm.event.type === 'message') {
    console.log(dm.event.senderId, dm.event.content?.text);
  }
}

const cached = result.conversationKeys.keys;
const event = chat.decryptEvent(oneEventB64, cached, senderSigningKeys);

const rawKey = cached[result.conversationKeys.latestVersion!];
const payload = chat.encryptMessage({
  messageId, senderId, conversationId, conversationKey: rawKey, text: 'Hi!',
  conversationKeyVersion, signingKeyVersion,
});

// ChatCore + import_keys, or chat_xdk::Chat + unlock().await
let result = chat.decrypt_events(&raw_events, &signing_keys);
let cached = &result.conversation_keys.keys;
let event = chat.decrypt_event(one_event_b64, cached, &sender_signing_keys)?;
// cached values are XChatConversationKey; encrypt_message wants owned bytes
let latest = result.conversation_keys.latest_version.as_deref().unwrap_or_default();
let conv_key = cached[latest].to_bytes();
let payload = chat.encrypt_message(EncryptMessageParams::new(
    &message_id, &sender_id, &conversation_id, conv_key, "Hi!",
    &conversation_key_version, &signing_key_version,
))?;

chat := chatxdk.New()
defer chat.Close()
blob, _ := chatxdk.Base64ToBytes(privateKeysB64)
_ = chat.ImportKeys(blob)
chat.SetKeyVersion(signingKeyVersion)

result, err := chat.DecryptEvents(rawEvents, signingKeys)
cached := result.ConversationKeys.Keys
event, err := chat.DecryptEvent(oneEventB64, cached, senderSigningKeys)
rawKey := cached[*result.ConversationKeys.LatestVersion]
payload, err := chat.EncryptMessage(chatxdk.EncryptMessageParams{
    MessageID: messageID, SenderID: senderID, ConversationID: conversationID,
    ConversationKey: rawKey, Text: "Hi!",
    ConversationKeyVersion: conversationKeyVersion, SigningKeyVersion: signingKeyVersion,
})
_ = event
_ = payload
_ = err

using var chat = new Chat();
chat.ImportKeys(privateKeyBytes);
chat.SetKeyVersion(signingKeyVersion);

var result = chat.DecryptEvents(rawEvents, signingKeys);
var cached = result.ConversationKeys.Keys;
var evt = chat.DecryptEvent(oneEventB64, cached, senderSigningKeys);
var payload = chat.EncryptMessage(new EncryptMessageParams {
    MessageId = messageId, SenderId = senderId, ConversationId = conversationId,
    ConversationKey = rawKey, Text = "Hi!",
    ConversationKeyVersion = conversationKeyVersion, SigningKeyVersion = signingKeyVersion,
});

try (Chat chat = new Chat()) {
    chat.importKeys(privateKeyBytes);
    chat.setKeyVersion(signingKeyVersion);

    DecryptEventsResult result = chat.decryptEvents(rawEvents, signingKeys);
    Map<String, byte[]> cached = result.conversationKeys.keys;
    JsonNode event = chat.decryptEvent(oneEventB64, cached, senderSigningKeys);

    EncryptMessageParams params = new EncryptMessageParams();
    params.messageId = messageId;
    params.senderId = senderId;
    params.conversationId = conversationId;
    params.conversationKey = rawKey;
    params.text = "Hi!";
    params.conversationKeyVersion = conversationKeyVersion;
    params.signingKeyVersion = signingKeyVersion;
    SendPayload payload = chat.encryptMessage(params);
}

Lifecycle and keys

Construct the SDK, store private keys (Juicebox PIN or a local key blob), register public keys with the Chat API, and set your registered public-key version after unlock or import. Call generate_keypairs once per device/app identity; post the registration payload to the public-keys endpoint. Use setup / unlock (and related PIN helpers) for Juicebox PIN storage on every binding. export_keys / import_keys (raw key-blob persistence for bots and servers) are available on the native bindings only—Python, Go, .NET, JVM, and Rust. The JS/WASM binding does not expose raw key export or import: in a browser any script that reaches the instance could exfiltrate the identity, so JS keeps keys inside Juicebox. A JS server that wants to avoid a Juicebox round-trip per request should reuse one unlocked Chat instance across requests, or run a native binding where key blobs are supported.

from chat_xdk import Chat

# Juicebox (client)
chat = Chat(juicebox_config_json)
chat.setup("YOUR_PIN")          # first time — generates keypairs
# chat.unlock("YOUR_PIN")        # later sessions
chat.set_key_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)
chat2.set_key_version(version)
blob = chat2.export_keys()       # treat as a password

import { createChat } from '@xdevplatform/chat-xdk';

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

// JS/WASM stores keys only through Juicebox — there is no raw key
// export/import here. For key-blob persistence, use a native binding.

// chat_xdk::Chat — async Juicebox unlock, or ChatCore + import_keys
chat.setup("YOUR_PIN").await?;
// chat.unlock("YOUR_PIN").await?;
chat.set_key_version(&version);
let publics = chat.get_public_keys()?;
let blob = chat.export_keys()?;
chat.import_keys(&blob)?;

chat := chatxdk.New()
defer chat.Close()

// Prefer ImportKeys for servers; Juicebox unlock where supported
keyBlob, _ := chatxdk.Base64ToBytes(privateKeysB64)
if err := chat.ImportKeys(keyBlob); err != nil {
    log.Fatal(err)
}
chat.SetKeyVersion(version)
publics, err := chat.GetPublicKeys()
blob, err := chat.ExportKeys()
_ = publics
_ = blob
_ = err

using var chat = new Chat();
chat.ImportKeys(privateKeyBytes);
// or Juicebox setup / unlock when config is available
chat.SetKeyVersion(version);
var publics = chat.GetPublicKeys();
var blob = chat.ExportKeys();

try (Chat chat = new Chat()) {
    chat.importKeys(privateKeyBytes);
    chat.setKeyVersion(version);
    var publics = chat.getPublicKeys();
    byte[] blob = chat.exportKeys();
}

The Juicebox config accepts three shapes: the X API juicebox_config object (recommended—passed verbatim), a full sdk_config wrapper, or a bare token_map. Optional: signature verification is on by default (reject_unverified = true)—call set_reject_unverified(false) to disable it (not recommended); update_config if Juicebox realm config changes; is_unlocked / has_identity_key for UI state. Full field lists live in the chat-xdk repo stubs.

Conversation keys

Three prepare methods each make one call do everything a key change needs: generate a fresh conversation key, encrypt it for every participant (from the public keys you pass), and sign the change. All return the same PreparedConversationChange shape, ready to POST—rename SDK field encrypted_key to encrypted_conversation_key in conversation_participant_keys, and map the action signatures into the required action_signatures body field.

Scenario	Method	Action signatures returned
Start a 1:1 (omit the conversation id—the SDK derives it) or rotate any conversation’s key (pass the id)	`prepare_conversation_key_change`	1
Create a group (id minted by `POST /2/chat/conversations/group/initialize`)	`prepare_group_create`	2—send both
Add members to a group	`prepare_group_members_change`	2—send both

Keep the raw key bytes for encrypt_message and media; never pass the API’s encrypted envelope into encrypt.

Verify fetched keys before wrapping. The prepare methods encrypt the fresh conversation key to whatever public keys you pass. Before passing them, call verify_key_binding(identity, signing, signature) on each fetched record—its public_key, signing_public_key, and identity_public_key_signature fields from the public-keys API—so a substituted identity key cannot receive the conversation key.

Use extract_conversation_keys on key-change event payloads to rebuild { keys, latest_version }. decrypt_conversation_key unwraps a single ECIES blob.

# 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(my_user_id, signing_key_version, 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)

const prepared = chat.prepareConversationKeyChange({
  senderId: myUserId, signingKeyVersion, 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);

let prepared = chat.prepare_conversation_key_change(
    ConversationKeyChangeParams::new(&my_user_id, &signing_key_version, 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)?;

prepared, err := chat.PrepareConversationKeyChange(chatxdk.ConversationKeyChangeParams{
    SenderID: myUserID, SigningKeyVersion: signingKeyVersion, 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

var prepared = chat.PrepareConversationKeyChange(new ConversationKeyChangeParams {
    SenderId = myUserId, SigningKeyVersion = signingKeyVersion, PublicKeys = participants,
});
var extracted = chat.ExtractConversationKeys(keyChangeBlobs);
var raw = extracted.Keys[extracted.LatestVersion];
var one = chat.DecryptConversationKey(encryptedBlob);

ConversationKeyChangeParams keyParams = new ConversationKeyChangeParams();
keyParams.senderId = myUserId;
keyParams.signingKeyVersion = signingKeyVersion;
keyParams.publicKeys = participants;
PreparedConversationChange prepared = chat.prepareConversationKeyChange(keyParams);
ConversationKeyBundle extracted = chat.extractConversationKeys(keyChangeBlobs);
byte[] raw = extracted.keys.get(extracted.latestVersion);
byte[] one = chat.decryptConversationKey(encryptedBlob);

For group create and member adds, pass the params each method needs (member/admin id lists for prepare_group_create; new plus current roster for prepare_group_members_change)—see Groups for samples. Both return two action signatures; the POST must include both.

Decrypt

decrypt_events is for history and backlog: it pulls conversation keys from the stream, returns decrypted messages, and collects per-event errors instead of failing the whole batch. decrypt_event is for a single live event when you already have a key cache; it raises/throws on failure. Pass signing keys so the SDK can verify senders. Map API public-key fields into SigningKeyEntry: public_key_version → public_key_version (same name), signing_public_key → public_key, public_key → identity_public_key, plus identity_public_key_signature and user_id. Verification is mandatory by default: omitting or passing an empty signing-key list does not skip it—signed events fail (collected in errors for decrypt_events, thrown for decrypt_event). To actually skip verification you must first call set_reject_unverified(false) (not recommended in production).

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.get("type") == "Message":
        text = ev.get("content", {}).get("text")

cached = result["conversation_keys"]["keys"]
live = chat.decrypt_event(one_event_b64, cached, signing_keys_for_sender)

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, signingKeysForSender);

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_for_sender)?;

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, signingKeysForSender)
_ = live
_ = err

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, signingKeysForSender);

DecryptEventsResult result = chat.decryptEvents(rawEvents, signingKeys);
Map<String, byte[]> cached = result.conversationKeys.keys;
JsonNode live = chat.decryptEvent(oneEventB64, cached, signingKeysForSender);

Encrypt and send helpers

encrypt_message builds the signed ciphertext for a text message (optional entities, attachments via media_hash_key, TTL, notify flags). Map the returned payload into the send-message body: encrypted_content → encoded_message_create_event, encoded_event_signature → encoded_message_event_signature, plus your message_id. Use encrypt_reply, encrypt_add_reaction, and encrypt_remove_reaction for replies and reactions (sequence_id targets the parent). encrypt / decrypt are for UTF-8 metadata under the conversation key (for example an encrypted group name)—not message envelopes. encrypt_stream / decrypt_stream encrypt attachment bytes; see Media. Low-level sign / verify / verify_key_binding support advanced flows; conversation-key changes, group creates, and member adds are signed by the prepare methods. The conversation id passed to encrypt_message / encrypt_reply can be any form you hold—A:B from events, A-B from listings or URL paths (in either order), or the bare recipient user id—the SDK canonicalizes it before signing. Group ids (prefixed with g) pass through unchanged.

payload = chat.encrypt_message(
    message_id, sender_id, conversation_id, raw_conversation_key, "Hello",
    conversation_key_version, signing_key_version,
    # Optional keyword args: entities, attachments, should_notify, ttl_msec
)
body = {
    "message_id": 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

reply = chat.encrypt_reply(
    reply_message_id, sender_id, conversation_id, raw_conversation_key,
    "Sounds good", conversation_key_version, signing_key_version,
    parent_sequence_id,  # reply_to_sequence_id — the message being replied to
)
name_ct = chat.encrypt("Group title", raw_conversation_key)
title = chat.decrypt(name_ct, raw_conversation_key)

const payload = chat.encryptMessage({
  messageId, senderId, conversationId, conversationKey: rawConversationKey, text: 'Hello',
  conversationKeyVersion, signingKeyVersion,
});
const body = {
  message_id: messageId,
  encoded_message_create_event: payload.encryptedContent,
  encoded_message_event_signature: payload.encodedEventSignature,
};

const reply = chat.encryptReply({
  messageId: replyMessageId, senderId, conversationId, conversationKey: rawConversationKey,
  text: 'Sounds good', conversationKeyVersion, signingKeyVersion,
  replyToSequenceId: parentSequenceId, // the message being replied to
});
const nameCt = chat.encrypt('Group title', rawConversationKey);
const title = chat.decrypt(nameCt, rawConversationKey);

// conv_key: XChatConversationKey from extract_conversation_keys / decrypt_conversation_key
let payload = chat.encrypt_message(EncryptMessageParams::new(
    &message_id, &sender_id, &conversation_id, conv_key.to_bytes(), "Hello",
    &conversation_key_version, &signing_key_version,
))?;
// Map payload fields into the send-message JSON body as above
let name_ct = chat.encrypt("Group title", &conv_key)?;
let title = chat.decrypt(&name_ct, &conv_key)?;

payload, err := chat.EncryptMessage(chatxdk.EncryptMessageParams{
    MessageID: messageID, SenderID: senderID, ConversationID: conversationID,
    ConversationKey: rawKey, Text: "Hello",
    ConversationKeyVersion: conversationKeyVersion, SigningKeyVersion: signingKeyVersion,
})
// body: message_id, encoded_message_create_event, encoded_message_event_signature
nameCt, err := chat.Encrypt("Group title", rawKey)
title, err := chat.Decrypt(nameCt, rawKey)
_ = payload
_ = title
_ = err

var payload = chat.EncryptMessage(new EncryptMessageParams {
    MessageId = messageId, SenderId = senderId, ConversationId = conversationId,
    ConversationKey = rawKey, Text = "Hello",
    ConversationKeyVersion = conversationKeyVersion, SigningKeyVersion = signingKeyVersion,
});
// Map EncryptedContent / EncodedEventSignature into the send-message body
var nameCt = chat.Encrypt("Group title", rawKey);
var title = chat.Decrypt(nameCt, rawKey);

EncryptMessageParams params = new EncryptMessageParams();
params.messageId = messageId;
params.senderId = senderId;
params.conversationId = conversationId;
params.conversationKey = rawKey;
params.text = "Hello";
params.conversationKeyVersion = conversationKeyVersion;
params.signingKeyVersion = signingKeyVersion;
SendPayload payload = chat.encryptMessage(params);
// Map to encoded_message_create_event / encoded_message_event_signature on POST

String nameCt = chat.encrypt("Group title", rawKey);
String title = chat.decrypt(nameCt, rawKey);

Media streams

Encrypt file bytes with the same conversation key used for text, upload via Chat media APIs, and attach media_hash_key on encrypt_message. This is not the Posts media model (expansions=attachments.media_keys). Full upload/download flow: Media.

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)

const ciphertext = chat.encryptStream(fileBytes, rawConversationKey);
// Upload `ciphertext`; mediaHashKey comes from the upload finalize step.
const plain = chat.decryptStream(ciphertext, rawConversationKey);

// 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)?;

ciphertext, err := chat.EncryptStream(fileBytes, rawKey)
plain, err := chat.DecryptStream(ciphertext, rawKey)
_ = plain
_ = err

var ciphertext = chat.EncryptStream(fileBytes, rawKey);
var plain = chat.DecryptStream(ciphertext, rawKey);

byte[] ciphertext = chat.encryptStream(fileBytes, rawKey);
byte[] plain = chat.decryptStream(ciphertext, rawKey);

Incremental streaming for large media

For large files, avoid holding the whole payload in memory: stream_encryptor() / stream_decryptor() return a StreamEncryptor / StreamDecryptor you feed in chunks (about 1 MB each) with push(chunk), then call finish() once at the end. On decrypt, finish() detects a truncated stream (it fails if input ended before the final frame), so don’t treat pushed plaintext as complete until it succeeds.

JS/WASM only: finish() consumes and frees the underlying WASM object—never call free() after finish() (it throws). Call free() only to abandon a stream before finishing (e.g. on an error path).

Python
TypeScript

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)

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);

Utilities

Base64/hex helpers, MIME sniffing, and image dimensions are available as module-level functions (Python/JS/Rust/Go) or ChatXdkUtilities (C#/Java)—useful when building attachment metadata without pulling in extra libraries.

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)

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;

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));

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

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;

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;

Important types

These conceptual types show up across languages (exact field names differ; JS often uses camelCase event discriminators like message):

SendPayload — return value of encrypt_message and related encrypt helpers; map into the Chat API send body.
PublicKeyRegistrationPayload — output of generate_keypairs / public-key getters for the add-public-key API.
SigningKeyEntry — sender public material passed into decrypt for signature verification.
PreparedConversationChange — output of the three prepare methods: the derived or passed conversation_id, the raw conversation_key bytes, conversation_key_version, participant_keys (user_id, encrypted_key, public_key_version), and action_signatures (message_id, encoded_message_event_detail, signature, signature_version, public_key_version, optional signature_payload—omitted on key-change signatures because that payload embeds the plaintext key).
DecryptEventsResult — messages, optional errors, and extracted conversation_keys.

For complete field lists, use language stubs in the chat-xdk repo (docs/API.md, *.pyi, index.d.ts).

Errors

Python typically raises ValueError with a descriptive message (for example an invalid PIN). TypeScript/JavaScript throws Error. Go returns (value, error). Prefer decrypt_events for history so one bad event does not abort the batch; inspect the errors collection for partial failures. Some verification errors are permanent. Signatures are immutable and verified by rebuilding the signed payload from the event itself, so an old event that fails with signature missing or no matching signing key or an ECDSA mismatch will fail on every future load—no retry, key refresh, or API call can heal it. Treat these as tombstones, not transient errors. Rotating the conversation key starts a clean, verifiable history from that point forward.

Next steps

Getting Started

Wire Chat XDK to the Chat API

Media

Stream encrypt and media REST

Real-time events

Webhooks and activity delivery

Troubleshooting

Common failures

​Install

​Quick start

​Lifecycle and keys

​Conversation keys

​Decrypt

​Encrypt and send helpers

​Media streams

​Incremental streaming for large media

​Utilities

​Important types

​Errors

​Next steps

Getting Started

Media

Real-time events

Troubleshooting

Install

Quick start

Lifecycle and keys

Conversation keys

Decrypt

Encrypt and send helpers

Media streams

Incremental streaming for large media

Utilities

Important types

Errors

Next steps