Chat XDK

https://github.com/xdevplatform/chat-xdk
Admin
Chat XDK is a cryptographic SDK for X Chat that provides secure key management, message encryption,...
Tokens:97,179
Snippets:543
Trust Score:9.5
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Run an example (bash)

Source: https://github.com/xdevplatform/chat-xdk/blob/main/examples/README.md

Commands to set up and run an example: copy the .env.example and follow the per-language README.

```bash
cd examples/<language>
cp .env.example .env   # set X_ACCESS_TOKEN + CHAT_CONVERSATION_ID
# follow the per-language README to build and run
```

--------------------------------

### Setup from source with maturin develop

Source: https://github.com/xdevplatform/chat-xdk/blob/main/crates/pyo3/README.md

Editable install from source. Requires Python 3.10+, Rust (stable), and maturin.

```bash
cd crates/pyo3
pip install maturin
maturin develop
```

--------------------------------

### Get an access token with xurl (bash)

Source: https://github.com/xdevplatform/chat-xdk/blob/main/examples/README.md

Steps to install xurl, register app credentials, run the OAuth2 flow, and verify the token. The token is stored in ~/.xurl.

```bash
# 1. Install (macOS)
brew install --cask xdevplatform/tap/xurl

# 2. Register your app's credentials (from the X Developer Portal)
xurl auth apps add my-bot --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET

# 3. Run the OAuth2 user-context flow (opens a browser, asks for DM scopes)
xurl auth oauth2 --app my-bot

# 4. Verify it works
xurl /2/users/me
```

--------------------------------

### JavaScript/WASM: First boot with createChat and setup

Source: https://github.com/xdevplatform/chat-xdk/blob/main/docs/API.md

First boot flow for a brand-new user: create the chat without a juicebox_config, generate keypairs, POST them to /2/users/:id/public_keys, then update the config and call setup with the passcode.

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

const chat = await createChat({
  getAuthToken: async (realmId) => await backend.getToken(realmId),
});
const payload = chat.generateKeypairs();
// … POST payload to /2/users/:id/public_keys, GET juicebox_config back …
chat.updateConfig(configJson);
await chat.setup("2580");
```

--------------------------------

### setup

Source: https://github.com/xdevplatform/chat-xdk/blob/main/docs/API.md

Initializes the key storage with a PIN and returns the public keys.

```APIDOC
## setup

### Description
Initializes the key storage with a PIN and returns the public keys.

### Method
setup

### Parameters
- **pin** (byte array/string) - Required - The PIN to set up the key storage.
- **configJSON** (string) - Optional - Configuration in JSON format (Go and JVM only).

### Returns
- **PublicKeys** - The public keys generated during setup.

### Language Signatures
- **Rust**: `async setup(pin: &[u8]) → PublicKeys`
- **JavaScript**: `setup(pin: string | Uint8Array) → Promise<PublicKeys>`
- **Python**: `setup(pin: str) → PublicKeys`
- **Go**: `Setup(pin []byte, configJSON string) (*PublicKeys, error)`
- **JVM**: `setup(String pin, String configJson)`
- **.NET**: `Setup(string pin, string configJson)`
```

--------------------------------

### Install chatxdk with pip

Source: https://github.com/xdevplatform/chat-xdk/blob/main/crates/pyo3/README.md

Install the PyPI distribution `chatxdk`; import it as `chat_xdk`.

```bash
pip install chatxdk
```

--------------------------------

### Quick start: initial setup and later session with createChat

Source: https://github.com/xdevplatform/chat-xdk/blob/main/crates/wasm/js/README.md

First boot creates a chat without juicebox_config (a new user has none yet), generates keypairs, POSTs them, then updates config and sets up key storage. Later sessions supply the config up front and unlock. Both paths use the same createChat API; later sessions also set identity, cache, signing keys, and perform decryption/encryption operations. Requires the juicebox-sdk peer dependency for setup/unlock.

```typescript
import { createChat } from "@xdevplatform/chat-xdk";

const chat = await createChat({
  getAuthToken: async (realmId) => await myBackend.getToken(realmId),
});
const payload = chat.generateKeypairs();
// … POST payload to /2/users/:id/public_keys, GET juicebox_config back …
chat.updateConfig(configJson);
await chat.setup("2580");
```

```typescript
import { createChat } from "@xdevplatform/chat-xdk";

const chat = await createChat({
  juiceboxConfig: configJson,
  getAuthToken: async (realmId) => await myBackend.getToken(realmId),
});
await chat.unlock("2580");

// Set the session once: your user id + registered signing-key version,
// the participants' signing keys, and the opt-in conversation-key cache.
chat.setIdentity("111", "v1");
chat.setCacheKeys(true);
// Each signing-key entry carries all five fields from the X API
// public keys response.
chat.setSigningKeys([
  {
    userId: "111",
    publicKeyVersion: "v1",
    publicKey: "BASE64...",
    identityPublicKey: "BASE64...",
    identityPublicKeySignature: "BASE64...",
  },
  {
    userId: "222",
    publicKeyVersion: "v1",
    publicKey: "BASE64...",
    identityPublicKey: "BASE64...",
    identityPublicKeySignature: "BASE64...",
  },
]);

// Initial load — batch decrypt with automatic key extraction. Signing keys
// come from the store; the verified conversation keys populate the cache.
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);
  }
}

// Individual events after the initial load: conversation keys resolve from
// the cache and signing keys from the store (pass either explicitly to
// override).
const event = chat.decryptEvent(webhookEventB64);

// Sending resolves the identity and conversation key from the session too.
const payload = chat.encryptMessage({ conversationId: event.conversationId, text: "hi!" });
// Reply / react by handing back the raw event being answered.
const reply = chat.encryptReply({
  conversationId: event.conversationId,
  text: "pong",
  replyToEvent: webhookEventB64,
});
const reaction = chat.encryptAddReaction({ emoji: "👍", targetEvent: webhookEventB64 });
```

--------------------------------

### setup()

Source: https://github.com/xdevplatform/chat-xdk/blob/main/docs/API.md

Initializes the SDK and returns the public keys for the user. This method must be called before other operations.

```APIDOC
## setup()

### Description
Initializes the SDK and returns the public keys for the user. This method must be called before other operations.

### Method
setup

### Returns
- **PublicKeys** - An object containing the identity and signing public keys.

### Response Example
{
  "identity": "Base64-encoded identity public key (P-256 SEC1)",
  "signing": "Base64-encoded signing public key (P-256 SEC1)",
  "version": "Key version identifier (may be empty)"
}
```

--------------------------------

### Build native library and install JVM binding

Source: https://github.com/xdevplatform/chat-xdk/blob/main/examples/jvm/README.md

Commands to build the native chat_xdk_dotnet library and install the JVM binding into the local Maven repository. Run from the repo root.

```bash
cargo build -p chat-xdk-dotnet --release
cd crates/jvm/java/chatxdk && mvn install
```

--------------------------------

### Run the browser app

Source: https://github.com/xdevplatform/chat-xdk/blob/main/examples/js/README.md

Set up environment, build the browser-target WASM package, and start the dev server on http://localhost:8787.

```bash
cp .env.example .env   # set X_ACCESS_TOKEN
npm run build:wasm     # build a browser (web-target) WASM package
npm start              # serve on http://localhost:8787
```

--------------------------------

### Install chat-xdk and optional juicebox-sdk

Source: https://github.com/xdevplatform/chat-xdk/blob/main/crates/wasm/js/README.md

Install the chat-xdk package. Juicebox SDK is an optional peer dependency required only for PIN-based key storage operations (setup, unlock, changePin). The compiled WASM engine is included in the package, so no build step is needed.

```bash
npm install @xdevplatform/chat-xdk
```

```bash
npm install juicebox-sdk   # only needed for setup()/unlock()/changePin()
```

--------------------------------

### Run the bot (first run and subsequent runs)

Source: https://github.com/xdevplatform/chat-xdk/blob/main/examples/dotnet/README.md

First run with no keys prints a registration payload and private blob. After configuring .env, re-run to start the bot.

```bash
cp .env.example .env
# First run with no keys prints a registration payload + a private blob:
dotnet run --project ChatBot
# Paste CHAT_PRIVATE_KEYS_B64 into .env, register the public key with the X API,
# set X_ACCESS_TOKEN + CHAT_CONVERSATION_ID, then re-run.
dotnet run --project ChatBot
```

--------------------------------

### Chat (Java) - Session Setup and Event Decryption

Source: https://github.com/xdevplatform/chat-xdk/blob/main/docs/API.md

Demonstrates creating a Chat instance, unlocking, setting identity and keys, and decrypting events.

```APIDOC
## Chat (Java) - Session Setup and Event Decryption

### Description
Creates a Chat instance, unlocks with a PIN, sets identity and keys, and decrypts events.

### Method
Constructor and methods

### Endpoint
N/A (SDK)

### Parameters
- `pin` (string) - Required - PIN for unlocking.
- `juiceboxConfigJson` (string) - Required - Juicebox configuration JSON.
- `myUserId` (string) - Required - User ID for identity.
- `mySigningKeyVersion` (string) - Required - Signing key version.
- `signingKeys` (Map) - Required - Signing keys for all participants.
- `rawEvents` (object) - Required - Raw events to decrypt.

### Request Example
```java
try (Chat chat = new Chat()) {
    chat.unlock("2580", juiceboxConfigJson);
    chat.setIdentity(myUserId, mySigningKeyVersion);
    chat.setCacheKeys(true);
    chat.setSigningKeys(signingKeys);
    DecryptEventsResult batch = chat.decryptEvents(rawEvents, null);
}
```

### Response
#### Success Response
- `batch.messages` (array) - List of decrypted messages.
- `dm.event` (JsonNode) - Decrypted event.

#### Response Example
```java
for (DecryptedMessage dm : batch.messages) {
    JsonNode evt = dm.event;
    if (evt != null && "Message".equals(evt.path("type").asText())) {
        String text = evt.path("content").path("text").asText();
    }
}
```
```

--------------------------------

### Build release wheel with maturin

Source: https://github.com/xdevplatform/chat-xdk/blob/main/crates/pyo3/README.md

Build a release wheel and install it with pip.

```bash
maturin build --release
pip install target/wheels/*.whl
```

--------------------------------

### Run offline crypto tests for all bindings (make test-all)

Source: https://github.com/xdevplatform/chat-xdk/blob/main/README.md

Command to run offline crypto tests for every binding from the examples directory. No credentials are required.

```bash
cd examples && make test-all      # offline crypto tests for every binding (no creds)
```

--------------------------------

### Chat (C#) - Session Setup and Event Decryption

Source: https://github.com/xdevplatform/chat-xdk/blob/main/docs/API.md

Demonstrates creating a Chat instance, configuring it, unlocking, setting identity and keys, and decrypting events.

```APIDOC
## Chat (C#) - Session Setup and Event Decryption

### Description
Creates a Chat instance, configures it with a juicebox config, unlocks with a PIN, sets identity and keys, and decrypts events.

### Method
Constructor and methods

### Endpoint
N/A (SDK)

### Parameters
- `juiceboxConfigJson` (string) - Required - Juicebox configuration JSON.
- `pin` (string) - Required - PIN for unlocking.
- `myUserId` (string) - Required - User ID for identity.
- `mySigningKeyVersion` (string) - Required - Signing key version.
- `signingKeys` (object) - Required - Signing keys for all participants.
- `rawEvents` (object) - Required - Raw events to decrypt.

### Request Example
```csharp
using var chat = new Chat();
chat.UpdateConfig(juiceboxConfigJson);
chat.Unlock(pin, juiceboxConfigJson);
chat.SetIdentity(myUserId, mySigningKeyVersion);
chat.SetCacheKeys(true);
chat.SetSigningKeys(signingKeys);
var result = chat.DecryptEvents(rawEvents);
```

### Response
#### Success Response
- `result.Messages` (array) - List of decrypted messages.
- `dm.Event` (JsonElement) - Decrypted event.

#### Response Example
```csharp
foreach (var dm in result.Messages)
{
    if (dm.Event.GetProperty("type").GetString() == "Message")
        Console.WriteLine(dm.Event.GetProperty("content").GetProperty("text").GetString());
}
```
```

--------------------------------

### get_public_keys()

Source: https://github.com/xdevplatform/chat-xdk/blob/main/docs/API.md

Retrieves the current public keys for the user. Returns the same structure as setup().

```APIDOC
## get_public_keys()

### Description
Retrieves the current public keys for the user. Returns the same structure as setup().

### Method
get_public_keys

### Returns
- **PublicKeys** - An object containing the identity and signing public keys.

### Response Example
{
  "identity": "Base64-encoded identity public key (P-256 SEC1)",
  "signing": "Base64-encoded signing public key (P-256 SEC1)",
  "version": "Key version identifier (may be empty)"
}
```

--------------------------------

### Example architecture flowchart (Mermaid)

Source: https://github.com/xdevplatform/chat-xdk/blob/main/examples/README.md

Shows the separation between the crypto core, I/O layer, and bot loop, and how the offline test exercises the crypto core directly.

```mermaid
flowchart LR
    subgraph Example["each example (per language)"]
        bot["bot loop<br/>receive → reply → send"]
        core["crypto core<br/>(wraps the binding)"]
        io["I/O layer<br/>(env config + HTTP)"]
        bot --> core
        bot --> io
    end
    core --> binding["chat-xdk binding"]
    io --> api["X Chat API"]
    test["offline test"] --> core
```

--------------------------------

### Add the chatxdk Go module with go get

Source: https://github.com/xdevplatform/chat-xdk/blob/main/crates/go/README.md

Use this command to add the chatxdk module to your Go project. The static library for your platform is already committed under libs/.

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

--------------------------------

### DecryptEvent Go example

Source: https://github.com/xdevplatform/chat-xdk/blob/main/docs/API.md

Go example of DecryptEvent. Returns an event and error; panics on error and prints the event type.

```go
event, err := chat.DecryptEvent(eventB64, cachedKeys, senderSigningKeys)
if err != nil {
    panic(err)
}
fmt.Println(event.Type)
```

--------------------------------

### DecryptEvent .NET example

Source: https://github.com/xdevplatform/chat-xdk/blob/main/docs/API.md

.NET example of DecryptEvent. Checks if the event type is "Message" and prints the text content.

```csharp
var eventJson = chat.DecryptEvent(eventB64, cachedKeys, senderSigningKeys);
if (eventJson.GetProperty("type").GetString() == "Message")
    Console.WriteLine(eventJson.GetProperty("content").GetProperty("text").GetString());
```

--------------------------------

### decryptEvent JVM example

Source: https://github.com/xdevplatform/chat-xdk/blob/main/docs/API.md

JVM example of decryptEvent. Checks if the event type is "Message" and prints the text content.

```java
JsonNode event = chat.decryptEvent(eventB64, cachedKeys, senderSigningKeys);
if ("Message".equals(event.path("type").asText())) {
    System.out.println(event.path("content").path("text").asText());
}
```

--------------------------------

### Run the bot: copy .env and run cargo

Source: https://github.com/xdevplatform/chat-xdk/blob/main/examples/rust/README.md

Copy the .env.example file, then run the bot with cargo run. On first run, it prints a registration payload and a private blob. After configuring .env with the required keys, re-run cargo run.

```bash
cp .env.example .env
# First run with no keys prints a registration payload + a private blob:
cargo run
# Paste CHAT_PRIVATE_KEYS_B64 into .env, register the public key with the X API,
# set X_ACCESS_TOKEN + CHAT_CONVERSATION_ID, then re-run.
cargo run
```

--------------------------------

### decrypt_event Python example

Source: https://github.com/xdevplatform/chat-xdk/blob/main/docs/API.md

Python example of decrypt_event. Checks if the event type is "Message" and prints the text content.

```python
event = chat.decrypt_event(event_b64, cached_keys, sender_signing_keys)
if event["type"] == "Message":
    print(event["content"]["text"])
```

--------------------------------

### Register your key (one-time)

Source: https://github.com/xdevplatform/chat-xdk/blob/main/examples/js/README.md

Build the WASM package and run the registration script with a confirmation flag. This is rate-limited and should be run only once.

```bash
npm run build:wasm                                    # once per Rust change
X_ACCESS_TOKEN=... CHAT_PIN=... npm run register -- --confirm
```

--------------------------------

### decryptEvent JavaScript example

Source: https://github.com/xdevplatform/chat-xdk/blob/main/docs/API.md

JavaScript example of decryptEvent using cached keys from a previous decryptEvents call. Passes a signing key entry with userId, publicKeyVersion, publicKey, identityPublicKey, and identityPublicKeySignature. Logs event.type, senderId, content.text, and verified.

```typescript
// You cached keys from a previous decryptEvents call
const cachedKeys = previousResult.conversationKeys.keys;

// A new event arrives via webhook
const event = chat.decryptEvent(
  webhookEventB64,
  cachedKeys,
  [{ userId: "111", publicKeyVersion: "v2", publicKey: "BASE64...", identityPublicKey: "BASE64...", identityPublicKeySignature: "BASE64..." }]
);

console.log(event.type);             // "message"
console.log(event.senderId);         // "111"
console.log(event.content.text);     // "hello"
console.log(event.verified);         // true
```

--------------------------------

### Go: chatxdk.New

Source: https://github.com/xdevplatform/chat-xdk/blob/main/docs/API.md

Creates a new chat client instance. Must be closed with Close() when done.

```APIDOC
## Go: chatxdk.New

### Description
Creates a new chat client instance. Must be closed with Close() when done.

### Method
New

### Endpoint
chatxdk.New()

### Parameters
None

### Request Example
```go
chat := chatxdk.New()
defer chat.Close()
```

### Response
#### Success Response
- **chat** (*chatxdk.Chat) - The chat client instance

#### Response Example
```go
chat := chatxdk.New()
```
```

--------------------------------

### Tuple (Python)

Source: https://github.com/xdevplatform/chat-xdk/blob/main/docs/API.md

Python tuple representation of a rich-text entity as (start, end, entity_type).

```APIDOC
## Tuple (Python)

### Description
Python representation of a rich-text entity as a tuple `(start, end, entity_type)`. The `start` and `end` are byte offsets, and `entity_type` is one of the supported entity types.

### Fields
- **start** (int) - Required - Start byte offset in the message text.
- **end** (int) - Required - End byte offset in the message text.
- **entity_type** (str) - Required - One of the supported entity types, e.g. "url", "mention".

### Example
```python
# Example: [(0, 23, "url"), (25, 30, "mention")]
```
```

--------------------------------

### Quick Start: ChatXdk usage in C#

Source: https://github.com/xdevplatform/chat-xdk/blob/main/crates/dotnet/README.md

Shows the main workflow: configure, unlock, set identity, decrypt events, encrypt messages, and use stateless helpers. Includes comments for alternative key import and individual event decryption.

```csharp
using ChatXdk;

using var chat = new Chat();
chat.UpdateConfig(juiceboxConfigJson);
chat.Unlock(pin, juiceboxConfigJson);
// Or load a local key blob + its registered version instead of Juicebox:
// chat.ImportKeys(privateKeyBytes, registeredKeyVersion);

// Set the session once: your user id + registered signing-key version,
// the opt-in conversation-key cache, and the participants' signing keys.
chat.SetIdentity(myUserId, registeredKeyVersion);
chat.SetCacheKeys(true);
chat.SetSigningKeys(signingKeys);

// Batch load — signing keys come from the store; the verified conversation
// keys populate the cache.
var batch = chat.DecryptEvents(rawEventB64List);
foreach (var dm in batch.Messages)
{
    if (dm.Event.GetProperty("type").GetString() == "Message")
        Console.WriteLine(dm.Event.GetProperty("sender_id").GetString());
}

// Individual events: omitted arguments resolve from the session stores
// (pass conversation/signing keys explicitly to override).
var evt = chat.DecryptEvent(eventB64);
var conversationId = evt.GetProperty("conversation_id").GetString()!;

// Sending resolves the identity and conversation key from the session too.
var payload = chat.EncryptMessage(new EncryptMessageParams(conversationId, "hi!"));
// Reply / react by handing back the raw event being answered.
var reply = chat.EncryptReply(new EncryptReplyParams(conversationId, "pong", eventB64));
var reaction = chat.EncryptAddReaction(new EncryptReactionParams(eventB64, "👍"));

var plaintext = chat.Decrypt(encryptedGroupNameB64, convKeyBytes);
```

--------------------------------

### EntityTuple (JS)

Source: https://github.com/xdevplatform/chat-xdk/blob/main/docs/API.md

JavaScript tuple representation of a rich-text entity as an array [start, end, type].

```APIDOC
## EntityTuple (JS)

### Description
JavaScript representation of a rich-text entity as a tuple `[start, end, type]`. The `start` and `end` are byte offsets, and `type` is one of the supported entity types.

### Fields
- **start** (number) - Required - Start byte offset in the message text.
- **end** (number) - Required - End byte offset in the message text.
- **type** (string) - Required - One of the supported entity types, e.g. "url", "mention".

### Example
```typescript
const entities: EntityTuple[] = [[0, 23, 'url'], [25, 30, 'mention']];
```
```

--------------------------------

### Go: Use BytesToBase64, DetectMimeType, DetectImageDimensions

Source: https://github.com/xdevplatform/chat-xdk/blob/main/docs/API.md

Import the chatxdk package and call the utility functions. BytesToBase64 returns the base64 string and an error; DetectMimeType returns an empty string with nil error for unknown types; DetectImageDimensions returns a non-nil *ImageDimensions or nil.

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

b64, _ := chatxdk.BytesToBase64([]byte{1, 2, 3}) // "AQID"
mime, _ := chatxdk.DetectMimeType(imageBytes)   // "image/png" or "" if unknown
dims, _ := chatxdk.DetectImageDimensions(imageBytes) // non-nil *ImageDimensions or nil
```

--------------------------------

### EntityDescriptor (Rust)

Source: https://github.com/xdevplatform/chat-xdk/blob/main/docs/API.md

Rust struct representing a rich-text entity with start and end byte offsets and an entity type.

```APIDOC
## EntityDescriptor (Rust)

### Description
Rust struct representing a rich-text entity to embed in a message. The `start` and `end` fields are byte offsets within the message text, and `entity_type` is one of the supported entity types.

### Fields
- **start** (i32) - Required - Start byte offset in the message text.
- **end** (i32) - Required - End byte offset in the message text.
- **entity_type** (String) - Required - One of the supported entity types, e.g. "url", "mention".

### Example
```rust
pub struct EntityDescriptor {
    pub start: i32,
    pub end: i32,
    pub entity_type: String,
}
```
```

--------------------------------

### Run the headless bot

Source: https://github.com/xdevplatform/chat-xdk/blob/main/examples/js/README.md

Set up environment variables and run the bot. The bot echoes messages back (pong for ping, otherwise 'You said: …').

```bash
cp .env.example .env   # set X_ACCESS_TOKEN, CHAT_CONVERSATION_ID, CHAT_PRIVATE_KEYS_B64
npm run bot
```

--------------------------------

### Build managed wrapper with dotnet

Source: https://github.com/xdevplatform/chat-xdk/blob/main/crates/dotnet/README.md

Builds the .NET wrapper from the crates/dotnet/dotnet/ChatXdk directory. Requires the native library to be built first.

```bash
cd crates/dotnet/dotnet/ChatXdk
dotnet build -c Release
```
Tokens:
Raw