Getting Started with Chat API

Send and receive end-to-end encrypted direct messages on X: set up keys, initialize a conversation, send a message, and decrypt inbound traffic. X Chat apps use two pieces together:

Component	Role
Chat XDK	Encryption, decryption, signing, and private key storage (secure key backup or a key blob)
X API	Public keys, conversation keys, messages, and events—via the Python or TypeScript XDK, or HTTPS with a user access token

Prerequisites

Developer account and an app configured for OAuth 2.0
User access token with dm.read, dm.write, tweet.read, and users.read

1. Install dependencies

pip install chatxdk xdk

The PyPI package is chatxdk; import it as chat_xdk. Requires Python 3.10+.

npm install @xdevplatform/chat-xdk @xdevplatform/xdk
npm install juicebox-sdk   # optional peer dependency — required for setup()/unlock() secure key backup

The compiled WASM engine ships inside @xdevplatform/chat-xdk—no build step. Requires Node.js 18+.

[dependencies]
# chat-xdk-core is not yet on crates.io — use the git dependency
chat-xdk-core = { git = "https://github.com/xdevplatform/chat-xdk", tag = "v0.2.1" }
reqwest = { version = "0.12", features = ["blocking", "json"] }
serde_json = "1"
base64 = "0.22"
uuid = { version = "1", features = ["v4"] }

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

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

Precompiled static libraries are included (macOS arm64/amd64, Linux amd64 glibc/musl)—you need a C compiler but not Rust. Requires Go 1.21+.

dotnet add package XDevPlatform.ChatXdk

The package is self-contained: native libraries for macOS (arm64, x64), Linux (x64), and Windows (x64) ship inside it. Requires .NET 8+.

<dependency>
  <groupId>com.x</groupId>
  <artifactId>chatxdk</artifactId>
  <version>0.2.1</version>
</dependency>

Available on Maven Central. The jar bundles the native library for macOS (arm64, x64), Linux (x64), and Windows (x64)—no jna.library.path setup needed. Import from com.x.chatxdk. Requires JDK 17+.

Create an API client with your user OAuth 2.0 access token:

from xdk import Client

client = Client(access_token="YOUR_OAUTH2_USER_TOKEN")

import { Client } from '@xdevplatform/xdk';

const client = new Client({ accessToken: 'YOUR_OAUTH2_USER_TOKEN' });

let access_token = std::env::var("X_ACCESS_TOKEN")?;
let http = reqwest::blocking::Client::new();
let auth = format!("Bearer {access_token}");

accessToken := os.Getenv("X_ACCESS_TOKEN")
httpClient := &http.Client{Timeout: 30 * time.Second}

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new System.Net.Http.Headers.AuthenticationHeaderValue(
        "Bearer", Environment.GetEnvironmentVariable("X_ACCESS_TOKEN"));

String accessToken = System.getenv("X_ACCESS_TOKEN");
HttpClient http = HttpClient.newHttpClient();

2. Initialize the Chat XDK with existing keys

This step loads keys you already have—use it when this identity completed first-time setup before:

Secure key backup: construct the SDK with the juicebox_config from your public-key record, then unlock with your passcode to recover the private keys (for example, on a new device).
Key blob: import_keys with a blob you previously exported via export_keys.

Then set your registered public-key version (public_key_version on your record). Setting up for the first time? Construct the SDK the same way but skip unlock/import_keys, and continue to step 3 to create, back up, and register your keys.

import json
from chat_xdk import Chat

resp = client.chat.get_user_public_keys(
    "YOUR_USER_ID",
    public_key_fields=[
        "public_key_version", "public_key", "signing_public_key",
        "identity_public_key_signature", "juicebox_config",
    ],
)
record = resp.data[0]
signing_key_version = str(record["public_key_version"])

chat = Chat(json.dumps(record["juicebox_config"]))
chat.unlock("YOUR_PASSCODE")  # recovers keys stored by setup() during first-time setup (step 3)
chat.set_key_version(signing_key_version)

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

const resp = await client.chat.getUserPublicKeys('YOUR_USER_ID', {
  publicKeyFields: [
    'public_key_version', 'public_key', 'signing_public_key',
    'identity_public_key_signature', 'juicebox_config',
  ],
});
const record = resp.data[0];
const signingKeyVersion = String(record.public_key_version);

const chat = await createChat({
  juiceboxConfig: JSON.stringify(record.juicebox_config),
  getAuthToken: async (realmId) => getRealmTokenFromYourBackend(realmId),
});
await chat.unlock('YOUR_PASSCODE');
chat.setKeyVersion(signingKeyVersion);

use base64::{engine::general_purpose::STANDARD as B64, Engine};
use chat_xdk_core::ChatCore;

let mut chat = ChatCore::new();
let blob = B64.decode(std::env::var("PRIVATE_KEYS_B64")?)?;
let signing_key_version = std::env::var("SIGNING_KEY_VERSION").unwrap_or_else(|_| "1".into());
chat.import_keys(&blob)?;
chat.set_key_version(&signing_key_version);

import "github.com/xdevplatform/chat-xdk/go/chatxdk"

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

blob, err := chatxdk.Base64ToBytes(os.Getenv("PRIVATE_KEYS_B64"))
if err != nil {
    log.Fatal(err)
}
if err := chat.ImportKeys(blob); err != nil {
    log.Fatal(err)
}
signingKeyVersion := os.Getenv("SIGNING_KEY_VERSION")
if signingKeyVersion == "" {
    signingKeyVersion = "1"
}
chat.SetKeyVersion(signingKeyVersion)

using ChatXdk;

using var chat = new Chat();
var signingKeyVersion = Environment.GetEnvironmentVariable("SIGNING_KEY_VERSION") ?? "1";
chat.ImportKeys(Convert.FromBase64String(
    Environment.GetEnvironmentVariable("PRIVATE_KEYS_B64")!));
chat.SetKeyVersion(signingKeyVersion);

import com.x.chatxdk.Chat;

String signingKeyVersion = Optional.ofNullable(System.getenv("SIGNING_KEY_VERSION")).orElse("1");
try (Chat chat = new Chat()) {
    chat.importKeys(Base64.getDecoder().decode(System.getenv("PRIVATE_KEYS_B64")));
    chat.setKeyVersion(signingKeyVersion);
}

Server and bot samples often use a key blob (export_keys / import_keys). Client apps often use secure key backup (setup / unlock with a passcode). See the Chat XDK reference for both paths.

Bringing your own keys? import_keys only accepts the opaque blob produced by export_keys from the Chat XDK—it is a versioned, private serialization of the full key state, not raw or PEM-encoded P-256 keys. You cannot construct this blob yourself: generate keys through generate_keypairs (step 3), export the blob once, and store it base64-encoded. Hand-crafted or modified blobs fail to import.

3. Create and register keys (first-time setup)

Skip this step if you loaded existing keys in step 2. Otherwise, one-time setup for a new identity does three things:

Create the keypairs — generate_keypairs produces the identity and signing keypairs.
Register the public keys — POST the registration payload to the add-public-key endpoint so others can encrypt to you and verify your signatures.
Store the private keys — setup with a passcode writes them to secure key backup (clients), or export_keys returns a key blob for you to store securely (servers and bots).

from xdk.chat.models import AddUserPublicKeyRequest

registration = chat.generate_keypairs()
pk = registration.public_key
client.chat.add_user_public_key(
    "YOUR_USER_ID",
    AddUserPublicKeyRequest(
        public_key={
            "identity_public_key_signature": pk.identity_public_key_signature,
            "public_key": pk.public_key,
            "public_key_fingerprint": pk.public_key_fingerprint,
            "registration_method": pk.registration_method,
            "signing_public_key": pk.signing_public_key,
            "signing_public_key_signature": pk.signing_public_key_signature,
        },
        version=registration.version,
        generate_version=registration.generate_version,
    ),
)
chat.setup("YOUR_PASSCODE")
chat.set_key_version(str(registration.version or signing_key_version))

const registration = chat.generateKeypairs();
const pk = registration.publicKey;
await client.chat.addUserPublicKey('YOUR_USER_ID', {
  public_key: {
    identity_public_key_signature: pk.identityPublicKeySignature,
    public_key: pk.publicKey,
    public_key_fingerprint: pk.publicKeyFingerprint,
    registration_method: pk.registrationMethod,
    signing_public_key: pk.signingPublicKey,
    signing_public_key_signature: pk.signingPublicKeySignature,
  },
  version: registration.version,
  generate_version: registration.generateVersion,
});
await chat.setup('YOUR_PASSCODE');
chat.setKeyVersion(String(registration.version ?? signingKeyVersion));

let registration = chat.generate_keypairs()?;
let body = serde_json::to_value(&registration)?;
let resp = http
    .post(format!("https://api.x.com/2/users/{user_id}/public_keys"))
    .header("Authorization", &auth)
    .json(&body)
    .send()?;
if !resp.status().is_success() {
    anyhow::bail!("register keys: {}", resp.text()?);
}
let _blob = chat.export_keys()?; // store securely

registration, err := chat.GenerateKeypairs()
if err != nil {
    log.Fatal(err)
}
regJSON, _ := json.Marshal(registration)
req, _ := http.NewRequest(http.MethodPost,
    "https://api.x.com/2/users/"+userID+"/public_keys",
    bytes.NewReader(regJSON))
req.Header.Set("Authorization", "Bearer "+accessToken)
req.Header.Set("Content-Type", "application/json")
resp, err := httpClient.Do(req)
if err != nil {
    log.Fatal(err)
}
resp.Body.Close()
privateKeysB64, _ := chat.ExportKeys() // store securely
_ = privateKeysB64
chat.SetKeyVersion(signingKeyVersion)

var registration = chat.GenerateKeypairs();
var regJson = System.Text.Json.JsonSerializer.Serialize(registration);
using var content = new StringContent(regJson, Encoding.UTF8, "application/json");
using var regResp = await http.PostAsync(
    $"https://api.x.com/2/users/{Uri.EscapeDataString(userId)}/public_keys", content);
regResp.EnsureSuccessStatusCode();
var blob = chat.ExportKeys(); // store securely
chat.SetKeyVersion(signingKeyVersion);

var registration = chat.generateKeypairs();
String regJson = new ObjectMapper().writeValueAsString(registration);
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.x.com/2/users/" + userId + "/public_keys"))
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(regJson))
    .build();
HttpResponse<String> regResp = http.send(req, HttpResponse.BodyHandlers.ofString());
if (regResp.statusCode() >= 300) {
    throw new RuntimeException("register keys: " + regResp.body());
}
byte[] blob = chat.exportKeys(); // store securely
chat.setKeyVersion(signingKeyVersion);

Use a strong passcode for secure key backup. Losing the passcode or an unprotected key blob can prevent decrypting past messages.

4. Set up conversation keys

Call prepare_conversation_key_change with your user ID, your signing key version, and every participant’s identity public key. One call generates a fresh conversation key, encrypts it for each participant, and signs the change. POST the result to the add conversation keys endpoint (POST /2/chat/conversations/{id}/keys)—the body needs conversation_key_version, conversation_participant_keys (SDK encrypted_key → API encrypted_conversation_key), and action_signatures (required; the API rejects the call without them). Keep the raw conversation key for sending. The response returns the canonical conversation id (data.conversation_id—the hyphen-joined pair for a 1:1, or the g-prefixed id for a group) and the key change’s data.sequence_id. Use that returned id for subsequent requests instead of reconstructing it client-side. The same call also rotates keys later: pass the existing conversation id to prepare_conversation_key_change and POST with the newer key version. Rotate when you suspect the conversation key was exposed—rotation protects future messages only; messages encrypted under earlier key versions stay readable to anyone who holds those versions.

Verify fetched keys before wrapping. prepare_conversation_key_change encrypts the fresh conversation key to whatever public keys you pass. Check each fetched record first with verify_key_binding(identity, signing, signature)—passing the record’s 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.

def public_key_input(user_id: str) -> dict:
    r = client.chat.get_user_public_keys(
        user_id, public_key_fields=["public_key_version", "public_key"]
    ).data[0]
    return {"user_id": user_id, "public_key": r["public_key"], "key_version": r["public_key_version"]}

prepared = chat.prepare_conversation_key_change(
    "YOUR_USER_ID",
    signing_key_version,
    [public_key_input("YOUR_USER_ID"), public_key_input("RECIPIENT_USER_ID")],
    # conversation_id=None for a new 1:1; pass the id to rotate later
)
resp = client.chat.add_conversation_keys(
    "RECIPIENT_USER_ID",
    {
        "conversation_key_version": prepared["conversation_key_version"],
        "conversation_participant_keys": [
            {
                "user_id": pk["user_id"],
                "encrypted_conversation_key": pk["encrypted_key"],
                "public_key_version": pk["public_key_version"],
            }
            for pk in prepared["participant_keys"]
        ],
        "action_signatures": [
            {
                "message_id": sig["message_id"],
                "encoded_message_event_detail": sig["encoded_message_event_detail"],
                "message_event_signature": {
                    "signature": sig["signature"],
                    "public_key_version": sig["public_key_version"],
                    "signature_version": sig["signature_version"],
                },
            }
            for sig in prepared["action_signatures"]
        ],
    },
)
conversation_id = resp.data["conversation_id"]  # canonical id for later requests
sequence_id = resp.data["sequence_id"]
conv_key = prepared["conversation_key"]
conv_key_version = prepared["conversation_key_version"]

async function publicKeyInput(userId: string) {
  const r = (await client.chat.getUserPublicKeys(userId, {
    publicKeyFields: ['public_key_version', 'public_key'],
  })).data[0];
  return { userId, publicKey: r.public_key, keyVersion: r.public_key_version };
}

// Omit conversationId for a new 1:1; pass the id to rotate later
const prepared = chat.prepareConversationKeyChange({
  senderId: 'YOUR_USER_ID',
  signingKeyVersion,
  publicKeys: [
    await publicKeyInput('YOUR_USER_ID'),
    await publicKeyInput('RECIPIENT_USER_ID'),
  ],
});
const resp = await client.chat.addConversationKeys('RECIPIENT_USER_ID', {
  conversation_key_version: prepared.conversationKeyVersion,
  conversation_participant_keys: prepared.participantKeys.map((pk) => ({
    user_id: pk.userId,
    encrypted_conversation_key: pk.encryptedKey,
    public_key_version: pk.publicKeyVersion,
  })),
  action_signatures: prepared.actionSignatures.map((sig) => ({
    message_id: sig.messageId,
    encoded_message_event_detail: sig.encodedMessageEventDetail,
    message_event_signature: {
      signature: sig.signature,
      public_key_version: sig.publicKeyVersion,
      signature_version: sig.signatureVersion,
    },
  })),
});
const conversationId = resp.data.conversation_id; // canonical id for later requests
const sequenceId = resp.data.sequence_id;
const convKey = prepared.conversationKey;
const convKeyVersion = prepared.conversationKeyVersion;

// public_key_inputs: Vec<PublicKeyInput> from GET public keys
// (user_id, public_key, key_version ← public_key_version)
// new 1:1; set params.conversation_id = Some(id) to rotate later
let prepared = chat.prepare_conversation_key_change(
    ConversationKeyChangeParams::new(&sender_id, &signing_key_version, public_key_inputs),
)?;
let participant_keys: Vec<_> = prepared
    .participant_keys
    .iter()
    .map(|pk| {
        serde_json::json!({
            "user_id": pk.user_id,
            "encrypted_conversation_key": pk.encrypted_key,
            "public_key_version": pk.public_key_version,
        })
    })
    .collect();
let action_signatures: Vec<_> = prepared
    .action_signatures
    .iter()
    .map(|sig| {
        serde_json::json!({
            "message_id": sig.message_id,
            "encoded_message_event_detail": sig.encoded_message_event_detail,
            "message_event_signature": {
                "signature": sig.signature,
                "public_key_version": sig.public_key_version,
                "signature_version": sig.signature_version,
            },
        })
    })
    .collect();
let body = serde_json::json!({
    "conversation_key_version": prepared.conversation_key_version,
    "conversation_participant_keys": participant_keys,
    "action_signatures": action_signatures,
});
let resp: serde_json::Value = http
    .post(format!("https://api.x.com/2/chat/conversations/{recipient_id}/keys"))
    .header("Authorization", &auth)
    .json(&body)
    .send()?
    .json()?;
// Canonical id for later requests
let conversation_id = resp["data"]["conversation_id"].as_str().unwrap().to_string();
// conversation_key is Option<XChatConversationKey>; encrypt_message wants owned bytes
let conv_key = prepared.conversation_key.expect("key present").to_bytes();
let conv_key_version = prepared.conversation_key_version;

// KeyVersion comes from the public_key_version field on each record
prepared, err := chat.PrepareConversationKeyChange(chatxdk.ConversationKeyChangeParams{
    SenderID:          myUserID,
    SigningKeyVersion: signingKeyVersion,
    PublicKeys: []chatxdk.PublicKeyInput{
        {UserID: myUserID, PublicKey: myIdentityPubB64, KeyVersion: myKeyVersion},
        {UserID: recipientID, PublicKey: theirIdentityPubB64, KeyVersion: theirKeyVersion},
    },
    // ConversationID empty for a new 1:1; pass the id to rotate later
})
var parts []map[string]string
for _, pk := range prepared.ParticipantKeys {
    parts = append(parts, map[string]string{
        "user_id":                    pk.UserID,
        "encrypted_conversation_key": pk.EncryptedKey,
        "public_key_version":         pk.PublicKeyVersion,
    })
}
var sigs []map[string]any
for _, sig := range prepared.ActionSignatures {
    sigs = append(sigs, map[string]any{
        "message_id":                   sig.MessageID,
        "encoded_message_event_detail": sig.EncodedMessageEventDetail,
        "message_event_signature": map[string]string{
            "signature":          sig.Signature,
            "public_key_version": sig.PublicKeyVersion,
            "signature_version":  sig.SignatureVersion,
        },
    })
}
body, _ := json.Marshal(map[string]any{
    "conversation_key_version":      prepared.ConversationKeyVersion,
    "conversation_participant_keys": parts,
    "action_signatures":             sigs,
})
req, _ := http.NewRequest(http.MethodPost,
    "https://api.x.com/2/chat/conversations/"+recipientID+"/keys",
    bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+accessToken)
req.Header.Set("Content-Type", "application/json")
resp, err := httpClient.Do(req)
// Response data.conversation_id is the canonical id for later requests
// prepared.ConversationKey feeds EncryptMessage
_ = resp

// KeyVersion comes from the public_key_version field on each record
var prepared = chat.PrepareConversationKeyChange(new ConversationKeyChangeParams {
    SenderId = myUserId,
    SigningKeyVersion = signingKeyVersion,
    PublicKeys = new[] {
        new PublicKeyInput { UserId = myUserId, PublicKey = myPk, KeyVersion = myVer },
        new PublicKeyInput { UserId = recipientId, PublicKey = theirPk, KeyVersion = theirVer },
    },
}); // ConversationId null for a new 1:1; pass the id to rotate later
var keysBody = new {
    conversation_key_version = prepared.ConversationKeyVersion,
    conversation_participant_keys = prepared.ParticipantKeys.Select(pk => new {
        user_id = pk.UserId,
        encrypted_conversation_key = pk.EncryptedKey,
        public_key_version = pk.PublicKeyVersion,
    }),
    action_signatures = prepared.ActionSignatures.Select(sig => new {
        message_id = sig.MessageId,
        encoded_message_event_detail = sig.EncodedMessageEventDetail,
        message_event_signature = new {
            signature = sig.Signature,
            public_key_version = sig.PublicKeyVersion,
            signature_version = sig.SignatureVersion,
        },
    }),
};
var json = System.Text.Json.JsonSerializer.Serialize(keysBody);
using var content = new StringContent(json, Encoding.UTF8, "application/json");
using var resp = await http.PostAsync(
    $"https://api.x.com/2/chat/conversations/{Uri.EscapeDataString(recipientId)}/keys",
    content);
resp.EnsureSuccessStatusCode();
var data = System.Text.Json.JsonDocument.Parse(await resp.Content.ReadAsStringAsync())
    .RootElement.GetProperty("data");
string conversationId = data.GetProperty("conversation_id").GetString()!; // canonical id
byte[] convKey = prepared.ConversationKey!;
string convKeyVersion = prepared.ConversationKeyVersion;

// keyVersion comes from the public_key_version field on each record
PublicKeyInput mine = new PublicKeyInput();
mine.userId = myUserId; mine.publicKey = myIdentityPubB64; mine.keyVersion = myKeyVersion;
PublicKeyInput theirs = new PublicKeyInput();
theirs.userId = recipientId; theirs.publicKey = theirIdentityPubB64; theirs.keyVersion = theirKeyVersion;

ConversationKeyChangeParams keyParams = new ConversationKeyChangeParams();
keyParams.senderId = myUserId;
keyParams.signingKeyVersion = signingKeyVersion;
keyParams.publicKeys = List.of(mine, theirs);
// keyParams.conversationId null for a new 1:1; set the id to rotate later
PreparedConversationChange prepared = chat.prepareConversationKeyChange(keyParams);

List<Map<String, String>> parts = new ArrayList<>();
for (var pk : prepared.participantKeys) {
    parts.add(Map.of(
        "user_id", pk.userId,
        "encrypted_conversation_key", pk.encryptedKey,
        "public_key_version", pk.publicKeyVersion));
}
List<Map<String, Object>> sigs = new ArrayList<>();
for (var sig : prepared.actionSignatures) {
    sigs.add(Map.of(
        "message_id", sig.messageId,
        "encoded_message_event_detail", sig.encodedMessageEventDetail,
        "message_event_signature", Map.of(
            "signature", sig.signature,
            "public_key_version", sig.publicKeyVersion,
            "signature_version", sig.signatureVersion)));
}
ObjectMapper mapper = new ObjectMapper();
String body = mapper.writeValueAsString(Map.of(
    "conversation_key_version", prepared.conversationKeyVersion,
    "conversation_participant_keys", parts,
    "action_signatures", sigs));
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.x.com/2/chat/conversations/" + recipientId + "/keys"))
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> resp = http.send(req, HttpResponse.BodyHandlers.ofString());
JsonNode data = mapper.readTree(resp.body()).path("data");
String conversationId = data.path("conversation_id").asText(); // canonical id
byte[] convKey = prepared.conversationKey;
String convKeyVersion = prepared.conversationKeyVersion;

5. Send a message

Encrypt with the raw conversation key bytes. On the send request, map:

Chat XDK field	Request body field
`encrypted_content` / `encryptedContent` / `EncryptedContent`	`encoded_message_create_event`
`encoded_event_signature` / `encodedEventSignature` / `EncodedEventSignature`	`encoded_message_event_signature`
Your generated id	`message_id`

Use a hyphenated conversation id in the URL path when the API requires it (: → -). The SDK itself is flexible: encrypt_message and encrypt_reply accept the id in any form you hold—A:B from events, A-B from listings or URL paths (in either order), or just the recipient’s user id—and canonicalize it before signing. Group ids (prefixed with g) pass through unchanged.

import uuid
from xdk.chat.models import SendMessageRequest

message_id = str(uuid.uuid4())
payload = chat.encrypt_message(
    message_id,
    "YOUR_USER_ID",
    "CONVERSATION_ID",
    conv_key,
    "Hello!",
    conv_key_version,
    signing_key_version,
)
client.chat.send_message(
    "RECIPIENT_USER_ID",
    SendMessageRequest(
        message_id=message_id,
        encoded_message_create_event=payload.encrypted_content,
        encoded_message_event_signature=payload.encoded_event_signature,
    ),
)

import { randomUUID } from 'crypto';

const messageId = randomUUID();
const payload = chat.encryptMessage({
  messageId,
  senderId: 'YOUR_USER_ID',
  conversationId: 'CONVERSATION_ID',
  conversationKey: convKey,
  text: 'Hello!',
  conversationKeyVersion: convKeyVersion,
  signingKeyVersion,
});
await client.chat.sendMessage('RECIPIENT_USER_ID', {
  message_id: messageId,
  encoded_message_create_event: payload.encryptedContent,
  encoded_message_event_signature: payload.encodedEventSignature,
});

use chat_xdk_core::EncryptMessageParams;

let message_id = uuid::Uuid::new_v4().to_string();
let payload = chat.encrypt_message(EncryptMessageParams::new(
    &message_id,
    &sender_id,
    &conversation_id,
    conv_key,
    "Hello!",
    &conv_key_version,
    &signing_key_version,
))?;
let body = serde_json::json!({
    "message_id": message_id,
    "encoded_message_create_event": payload.encrypted_content,
    "encoded_message_event_signature": payload.encoded_event_signature,
});
let path_id = conversation_id.replace(':', "-");
http.post(format!("https://api.x.com/2/chat/conversations/{path_id}/messages"))
    .header("Authorization", &auth)
    .json(&body)
    .send()?;

messageID := uuid.NewString()
payload, err := chat.EncryptMessage(chatxdk.EncryptMessageParams{
    MessageID:              messageID,
    SenderID:               senderID,
    ConversationID:         conversationID,
    ConversationKey:        convKey,
    Text:                   "Hello!",
    ConversationKeyVersion: convKeyVersion,
    SigningKeyVersion:      signingKeyVersion,
})
body, _ := json.Marshal(map[string]string{
    "message_id":                      messageID,
    "encoded_message_create_event":    payload.EncryptedContent,
    "encoded_message_event_signature": payload.EncodedEventSignature,
})
pathID := strings.ReplaceAll(conversationID, ":", "-")
req, _ := http.NewRequest(http.MethodPost,
    "https://api.x.com/2/chat/conversations/"+pathID+"/messages",
    bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+accessToken)
req.Header.Set("Content-Type", "application/json")
resp, err := httpClient.Do(req)
_ = resp

var messageId = Guid.NewGuid().ToString();
var payload = chat.EncryptMessage(new EncryptMessageParams {
    MessageId = messageId,
    SenderId = senderId,
    ConversationId = conversationId,
    ConversationKey = convKey,
    Text = "Hello!",
    ConversationKeyVersion = convKeyVersion,
    SigningKeyVersion = signingKeyVersion,
});
var sendJson = System.Text.Json.JsonSerializer.Serialize(new Dictionary<string, string> {
    ["message_id"] = messageId,
    ["encoded_message_create_event"] = payload.EncryptedContent,
    ["encoded_message_event_signature"] = payload.EncodedEventSignature,
});
using var content = new StringContent(sendJson, Encoding.UTF8, "application/json");
var pathId = conversationId.Replace(':', '-');
using var resp = await http.PostAsync(
    $"https://api.x.com/2/chat/conversations/{Uri.EscapeDataString(pathId)}/messages",
    content);
resp.EnsureSuccessStatusCode();

EncryptMessageParams params = new EncryptMessageParams();
params.messageId = UUID.randomUUID().toString();
params.senderId = senderId;
params.conversationId = conversationId;
params.conversationKey = convKey;
params.text = "Hello!";
params.conversationKeyVersion = convKeyVersion;
params.signingKeyVersion = signingKeyVersion;
SendPayload payload = chat.encryptMessage(params);

String pathId = conversationId.replace(':', '-');
String sendJson = new ObjectMapper().writeValueAsString(Map.of(
    "message_id", params.messageId,
    "encoded_message_create_event", payload.encryptedContent,
    "encoded_message_event_signature", payload.encodedEventSignature));
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://api.x.com/2/chat/conversations/" + pathId + "/messages"))
    .header("Authorization", "Bearer " + accessToken)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(sendJson))
    .build();
http.send(req, HttpResponse.BodyHandlers.ofString());

6. Receive and decrypt

Use webhooks or the activity stream for live traffic, or page conversation events for history.

Live payload fields: encoded_event, optional conversation_key_change_event
History: GET /2/chat/conversations/{id}/events — prefer decrypt_events on all events plus meta.conversation_key_events
Pass the sender’s public keys into decrypt for signature verification (map API fields into SigningKeyEntry; see Chat XDK)
JavaScript uses camelCase event types (message); other languages use "Message" and snake_case fields in JSON

conversation_keys = {}  # conversation_id -> { version: key_bytes }

def signing_keys_for(user_id: str) -> list[dict]:
    resp = client.chat.get_user_public_keys(
        user_id,
        public_key_fields=[
            "public_key_version", "public_key", "signing_public_key", "identity_public_key_signature",
        ],
    )
    return [
        {
            "user_id": user_id,
            "public_key_version": r["public_key_version"],
            "public_key": r["signing_public_key"],
            "identity_public_key": r["public_key"],
            "identity_public_key_signature": r["identity_public_key_signature"],
        }
        for r in resp.data
    ]

def handle_payload(payload: dict):
    cid = payload["conversation_id"]
    if payload.get("conversation_key_change_event"):
        conversation_keys[cid] = chat.extract_conversation_keys(
            [payload["conversation_key_change_event"]]
        )["keys"]
    event = chat.decrypt_event(
        payload["encoded_event"],
        conversation_keys.get(cid, {}),
        signing_keys_for(payload["sender_id"]),
    )
    if event.get("type") == "Message" and event.get("content", {}).get("content_type") == "Text":
        print(event["sender_id"], event["content"]["text"], event.get("verified"))

const conversationKeys = new Map<string, Record<string, Uint8Array>>();

async function signingKeysFor(userId: string) {
  const resp = await client.chat.getUserPublicKeys(userId, {
    publicKeyFields: [
      'public_key_version', 'public_key', 'signing_public_key', 'identity_public_key_signature',
    ],
  });
  return resp.data.map((r: {
    public_key_version: string;
    public_key: string;
    signing_public_key: string;
    identity_public_key_signature: string;
  }) => ({
    userId,
    publicKeyVersion: r.public_key_version,
    publicKey: r.signing_public_key,
    identityPublicKey: r.public_key,
    identityPublicKeySignature: r.identity_public_key_signature,
  }));
}

async function handlePayload(payload: {
  conversation_id: string;
  encoded_event: string;
  sender_id: string;
  conversation_key_change_event?: string;
}) {
  const cid = payload.conversation_id;
  if (payload.conversation_key_change_event) {
    conversationKeys.set(
      cid,
      chat.extractConversationKeys([payload.conversation_key_change_event]).keys,
    );
  }
  const event = chat.decryptEvent(
    payload.encoded_event,
    conversationKeys.get(cid) ?? {},
    await signingKeysFor(payload.sender_id),
  );
  if (event.type === 'message' && event.content?.contentType === 'text') {
    console.log(event.senderId, event.content.text, event.verified);
  }
}

// Build Vec<SigningKeyEntry> from GET /2/users/{id}/public_keys
// (public_key_version, public_key, signing_public_key, identity_public_key_signature)

if let Some(kc) = key_change_b64.as_deref() {
    let extracted = chat.extract_conversation_keys(&[kc]);
    conv_keys.extend(extracted.keys);
}
let event = chat.decrypt_event(&encoded_event, &conv_keys, &sender_signing_keys)?;

if keyChange != "" {
    extracted, _ := chat.ExtractConversationKeys([]string{keyChange})
    for v, k := range extracted.Keys {
        convKeys[v] = k
    }
}
event, err := chat.DecryptEvent(encodedEvent, convKeys, senderSigningKeys)
if err == nil && event.Type == "Message" {
    fmt.Println(event.AsMessage().Text())
}

if (!string.IsNullOrEmpty(keyChangeB64))
{
    var extracted = chat.ExtractConversationKeys(new[] { keyChangeB64 });
    foreach (var kv in extracted.Keys)
        convKeys[kv.Key] = kv.Value;
}
var evt = chat.DecryptEvent(encodedEvent, convKeys, senderSigningKeys);
if (evt.GetProperty("type").GetString() == "Message")
    Console.WriteLine(evt.GetProperty("content").GetProperty("text").GetString());

if (keyChangeB64 != null && !keyChangeB64.isEmpty()) {
    var extracted = chat.extractConversationKeys(List.of(keyChangeB64));
    convKeys.putAll(extracted.keys);
}
JsonNode evt = chat.decryptEvent(encodedEvent, convKeys, senderSigningKeys);
if ("Message".equals(evt.path("type").asText())) {
    System.out.println(evt.path("content").path("text").asText());
}

Complete poll-and-reply bots for every language: chat-xdk/examples.

Best practices

Cache raw conversation keys and sender public keys; refresh on signature verification failures
Deduplicate live deliveries with event_uuid
Page event history until pagination is complete so key-change metadata is not missed
Do not log passcodes, private keys, or message plaintext in production
In web apps, keep OAuth tokens (and key backup realm token minting) on a server; prefer holding private keys only in the client Chat XDK

Next steps

Chat XDK

Methods and types for all language bindings

Media

Encrypted images and file attachments

Groups

Multi-participant conversations and metadata

Real-time events

Webhooks and activity delivery

Start here

Guides

API reference

Getting Started with Chat API

1. Install dependencies

2. Initialize the Chat XDK with existing keys

3. Create and register keys (first-time setup)

4. Set up conversation keys

5. Send a message

6. Receive and decrypt

Best practices

Next steps

Chat XDK

Media

Groups

Real-time events

​1. Install dependencies

​2. Initialize the Chat XDK with existing keys

​3. Create and register keys (first-time setup)

​4. Set up conversation keys

​5. Send a message

​6. Receive and decrypt

​Best practices

​Next steps

Chat XDK

Media

Groups

Real-time events

1. Install dependencies

2. Initialize the Chat XDK with existing keys

3. Create and register keys (first-time setup)

4. Set up conversation keys

5. Send a message

6. Receive and decrypt

Best practices

Next steps