> ## Documentation Index
> Fetch the complete documentation index at: https://x-preview-mintlify-7f49d7a1.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Chat XDK リファレンス
> サポートされる言語全体で X Chat の鍵管理、暗号化、復号、署名を処理する暗号化 SDK である Chat XDK のリファレンス。
**Chat XDK** は X Chat の鍵管理、暗号化、復号、署名を処理します。X の HTTP API を呼び出すことは**ありません** — [Python](/xdks/python/overview) または [TypeScript](/xdks/typescript/overview) **XDK**、あるいはユーザーアクセストークンを使った HTTPS と組み合わせてください。
アプリのウォークスルー: [Getting Started](/xchat/getting-started)。サンプルボット: [chat-xdk/examples](https://github.com/xdevplatform/chat-xdk/tree/main/examples)。
### インストール
```bash theme={null}
pip install chatxdk
```
PyPI パッケージは `chatxdk` です。`chat_xdk` としてインポートします。Python 3.10+ が必要です。
```bash theme={null}
npm install @xdevplatform/chat-xdk
npm install juicebox-sdk # optional peer dependency — required for setup()/unlock() secure key backup
```
コンパイル済みの WASM エンジンはパッケージに同梱されています。ビルド手順は不要です。Node.js 18+ が必要です。
```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" }
```
```bash theme={null}
go get github.com/xdevplatform/chat-xdk/go/chatxdk
```
プリコンパイル済みの静的ライブラリが含まれています（macOS arm64/amd64、Linux amd64 glibc/musl）。C コンパイラは必要ですが、Rust は不要です。Go 1.21+ が必要です。
```bash theme={null}
dotnet add package XDevPlatform.ChatXdk
```
パッケージは自己完結型です。macOS（arm64、x64）、Linux（x64）、Windows（x64）用のネイティブライブラリが同梱されています。.NET 8+ が必要です。
```xml theme={null}
com.x
chatxdk
0.4.0
```
Maven Central で入手できます。jar には macOS（arm64、x64）、Linux（x64）、Windows（x64）用のネイティブライブラリが同梱されており、`jna.library.path` の設定は不要です。`com.x.chatxdk` からインポートします。JDK 17+ が必要です。
***
## クイックスタート
鍵をロードし、identity を一度設定し、バックログを復号し、1 つのライブイベントを復号し、メッセージを暗号化します。[Getting Started](/xchat/getting-started) のように送信ボディを [`POST /2/chat/conversations/{id}/messages`](/x-api/chat/send-chat-message) に接続します。
スニペットは、最短の呼び出し形式のために 2 つの**オプションの**セッションストアを使用します: `set_signing_keys` は他の参加者の公開鍵を保持し（[public-keys エンドポイント](/x-api/chat/get-user-public-keys)から取得）、復号呼び出しは呼び出しごとの引数なしで送信者を検証でき、`set_cache_keys(true)` は SDK に各会話の検証済み鍵を記憶させるので、暗号化呼び出しは会話 ID とテキストだけを必要とします。どちらかをスキップして代わりに呼び出しごとに同じ値を渡してください — 両方のスタイルは同じように検証します；[復号](#decrypt) を参照してください。
```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
```
```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
```
```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
```
```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
```
```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
```
```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) 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
}
```
***
## ライフサイクルと鍵
SDK を構築し、秘密鍵を保存し（パスコード保護された安全な鍵バックアップまたはローカル鍵 blob）、Chat API で**公開**鍵を登録し、unlock または import の後に **`set_identity(user_id, signing_key_version)`** を呼び出します — これは、すべての署名付きアクションがデフォルトで使用する送信者と署名鍵バージョンを設定するため、encrypt および prepare メソッドは呼び出しごとの identity 引数なしで動作します。デバイス/アプリの identity ごとに `generate_keypairs` を一度呼び出します；登録ペイロードを public-keys エンドポイントに POST します。すべてのバインディングで安全な鍵バックアップに `setup` / `unlock`（および関連するパスコードヘルパー）を使用します。`export_keys` / `import_keys`（ボットとサーバー向けの生の鍵 blob 永続化）は**ネイティブバインディングのみ**で利用可能です — Python、Go、.NET、JVM、Rust。JS/WASM バインディングは生の鍵のエクスポートやインポートを公開しません: ブラウザではインスタンスに到達するあらゆるスクリプトが identity を流出させる可能性があるため、JS は鍵を安全な鍵バックアップ内に保持します。リクエストごとのバックアップ realm ラウンドトリップを避けたい JS サーバーは、リクエスト間でアンロック済みの 1 つの `Chat` インスタンスを再利用するか、鍵 blob がサポートされているネイティブバインディングを実行してください。
SDK は、登録済み公開鍵について X API が報告するバージョンも必要とします。これにより、他のバージョンを対象とする鍵変更エントリはスキップされます。`set_identity` は、これをユーザー ID と一緒に記録します；`import_keys` はオプション引数として直接受け付けます（Rust と Go は `import_keys_with_version` / `ImportKeysWithVersion` を使用します）。
```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
```
```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.
```
```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)?;
```
```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
```
```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();
```
```java theme={null}
try (Chat chat = new Chat()) {
chat.importKeys(privateKeyBytes, version);
chat.setIdentity(userId, version);
var publics = chat.getPublicKeys();
byte[] blob = chat.exportKeys();
}
```
安全な鍵バックアップの設定は 3 つの形式を受け付けます: X API の `juicebox_config` オブジェクト（推奨 — そのまま渡します）、完全な `sdk_config` ラッパー、または裸の `token_map`。
オプション: 署名検証はデフォルトで**オン**です（`reject_unverified = true`） — 無効にするには `set_reject_unverified(false)` を呼び出します（推奨されません）；バックアップ realm 設定が変更された場合は `update_config`；UI の状態のために `is_unlocked` / `has_identity_key`。完全なフィールドリストは [chat-xdk リポジトリ](https://github.com/xdevplatform/chat-xdk) のスタブにあります。
***
## 会話鍵
3 つの **prepare** メソッドは、鍵変更に必要なすべてを 1 回の呼び出しで実行します: 新しい会話鍵を生成し、（渡された公開鍵から）各参加者に対して暗号化し、変更に署名します。送信者 ID と署名鍵バージョンはセッション（`set_identity`）から取得されます；params 上で `sender_id` / `signing_key_version` を設定して上書きします。すべては同じ **`PreparedConversationChange`** 形状を返し、POST の準備ができています — `conversation_participant_keys` の SDK フィールド `encrypted_key` を **`encrypted_conversation_key`** にリネームし、アクション署名を必要な **`action_signatures`** ボディフィールドにマップします。
| シナリオ | メソッド | 返されるアクション署名 |
| :--------------------------------------------------------------- | :-------------------------------- | :---------- |
| 1:1 を開始（会話 ID を省略 — SDK が導出）または任意の会話の鍵をローテーション（ID を渡す） | `prepare_conversation_key_change` | 1 |
| グループを作成（`POST /2/chat/conversations/group/initialize` で発行された ID） | `prepare_group_create` | 2 — 両方を送信 |
| グループにメンバーを追加 | `prepare_group_members_change` | 2 — 両方を送信 |
`encrypt_message` およびメディア用に**未加工の**鍵バイトを保持してください；API の暗号化エンベロープを暗号化に渡さないでください。
**ラップする前に取得した鍵を検証してください。** prepare メソッドは、渡された任意の公開鍵に対して新しい会話鍵を暗号化します。渡す前に、各取得済みレコードに対して `verify_key_binding(identity, signing, signature)` を呼び出します — public-keys API のレコードの `public_key`、`signing_public_key`、`identity_public_key_signature` フィールドを渡します — 置き換えられた identity 鍵が会話鍵を受け取れないようにします。
鍵変更イベントペイロードに対して `extract_conversation_keys` を使い、`{ keys, latest_version }` を再構築します。`decrypt_conversation_key` は 1 つの ECIES blob をアンラップします。
```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)
```
```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);
```
```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)?;
```
```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
```
```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);
```
```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);
```
グループの作成とメンバー追加については、各メソッドが必要とする params を渡します（`prepare_group_create` にはメンバー/管理者 ID リスト；`prepare_group_members_change` には新規プラス現在のロスター） — サンプルは [Groups](/xchat/groups#create-the-group-and-establish-keys) を参照。両方とも**2 つ**のアクション署名を返します；POST には両方を含める必要があります。
***
## 復号
**`decrypt_events`** は履歴とバックログ用です: ストリームから会話鍵を取り出し、復号済みメッセージを返し、バッチ全体を失敗させる代わりにイベントごとのエラーを**収集**します。**`decrypt_event`** は 1 つのライブイベント用です；失敗時に raise/throw します。
SDK が送信者を検証できるように**署名鍵**を渡します。API の public-key フィールドを `SigningKeyEntry` にマップします: `public_key_version` → `public_key_version`（同じ名前）、`signing_public_key` → `public_key`、`public_key` → `identity_public_key`、加えて `identity_public_key_signature` と `user_id`。
2 つのオプトインセッションストアを使用すると、呼び出しごとの鍵引数を省略できます:
* **`set_signing_keys(entries)`** は参加者の署名鍵を保存します；署名鍵引数を省略（または空を渡す）した復号呼び出しは、代わりにストアを使用します。検証自体は変わりません — 鍵は復号中のイベントからではなく、この呼び出しを通してのみストアに入ります。各呼び出しは前のセットを置き換えます。
* **`set_cache_keys(true)`** は会話鍵キャッシュを有効にします（デフォルトではオフ）。有効な間、`decrypt_events` は、鍵変更が有効な署名を持っていた最新の鍵を会話ごとにキャッシュします；`decrypt_event` は会話鍵引数が省略されるとそこにフォールバックし、encrypt ヘルパーは省略された会話鍵をそこから解決します。無効にするとキャッシュはクリアされます。
明示的な空でない引数は常にストアより優先されます。明示的な呼び出しごとの引数はファーストクラスのままで — サーバーレスやマルチインスタンスデプロイでは正しい選択です。そこではリクエストが、ストアが空のフレッシュなインスタンスに着地することがあります。
検証はデフォルトで必須です: 署名鍵を省略してもそれをスキップしません。何も渡されず、何も保存されていない場合、署名付きイベントは失敗します（`decrypt_events` の場合は `errors` に収集され、`decrypt_event` の場合はスローされます）。実際に検証をスキップするには、最初に `set_reject_unverified(false)` を呼び出す必要があります（本番では推奨されません）。
```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)
```
```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);
```
```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)?;
```
```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
```
```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);
```
```java theme={null}
DecryptEventsResult result = chat.decryptEvents(rawEvents, signingKeys);
Map cached = result.conversationKeys.keys;
JsonNode live = chat.decryptEvent(oneEventB64, cached, signingKeys);
```
***
## 暗号化と送信ヘルパー
**`encrypt_message(conversation_id, text)`** はテキストメッセージ用の署名付き暗号文を構築します；オプションで `entities`、`attachments`（`media_hash_key` 経由）、`should_notify`、`ttl_msec`。送信者 ID はセッション（`set_identity`）から、会話鍵はオプトインの鍵キャッシュ（`set_cache_keys`）から解決されます — または `sender_id` / `signing_key_version` と `conversation_key` + `conversation_key_version` を明示的に渡します。SDK は **`message_id`**（署名付きイベントに埋め込まれた UUID）を生成し、ペイロードで返します — 自分で生成しないでください；再試行時には同じペイロードを再利用して、ID が二度と生成されないようにしてください。ペイロードを送信メッセージボディにマップします: `message_id` → **`message_id`**、`encrypted_content` → **`encoded_message_create_event`**、`encoded_event_signature` → **`encoded_message_event_signature`**。
**返信はイベントベースです。** `encrypt_reply(conversation_id, text, reply_to_event)` は返信対象の base64 未加工イベントを取ります。SDK はそこから引用プレビュー（シーケンス ID、送信者、テキスト、エンティティ、添付）を導出し、署名済みオリジナルを送信メッセージに埋め込むので、受信者は引用を検証できます。オリジナルが返信より古い鍵バージョンで暗号化された場合は `reply_to_ckces` — 未加工の鍵変更イベント — を渡してください。オリジナルが**編集された**場合は、未加工の編集イベントを `reply_to_edit_event` として渡します: プレビューは現在メッセージが述べている内容を引用し（テキストとエンティティは編集から来ます）、編集はオリジナルとともに受信者がチェックできるように移動します。明示的な `reply_to_*` フィールドは、未加工のイベントをもう保持していない呼び出し元の上書きとして残ります。
**リアクションもイベントベースです。** `encrypt_add_reaction(target_event, emoji)` と `encrypt_remove_reaction(...)` は、リアクション対象の未加工イベントから会話 ID とターゲットシーケンス ID を導出します；同じ params でリアクションを追加し、後で削除できます。未加工のイベントをもう保持していない場合のみ、`conversation_id` と `target_message_sequence_id` を明示的に設定してください。
受信側では、返信を引用する復号済みメッセージには **`reply_preview_validation`**（`"Valid"` / `"Invalid"`；JS バインディングは `'valid'` / `'invalid'` を使用）が付与されます: SDK は、埋め込まれたオリジナルの署名を、イベントに含まれる鍵ではなく、あなたの署名鍵に対して検証し、復号し、引用コンテンツと作者をそれと比較しました。プレビューが編集イベントを埋め込む場合、SDK は編集を同じ方法で検証し（同じ会話、同じ作者）、引用テキストを編集前のテキストではなく編集済みコンテンツと照合します。メッセージにプレビューがない、またはプレビューにオリジナルが埋め込まれていない場合、フィールドは存在しません。`Invalid` プレビューは信頼できないものとして扱ってください: メッセージ自体は真正ですが、引用素材はそうではありません — 引用は検証済みオリジナルからのみレンダリングしてください。
**`encrypt` / `decrypt`** は、会話鍵を使った UTF-8 メタデータ用です（たとえば暗号化されたグループ名） — メッセージエンベロープではありません。**`encrypt_stream` / `decrypt_stream`** は添付バイトを暗号化します；[Media](/xchat/media) を参照。低レベルの **`sign` / `verify` / `verify_key_binding`** は高度なフローをサポートします；会話鍵変更、グループ作成、メンバー追加は [prepare メソッド](#conversation-keys) が署名します。
`encrypt_message` / `encrypt_reply` に渡す会話 ID は、保持している任意の形式で構いません — イベントからの `A:B`、リストや URL パスからの `A-B`（どちらの順序でも）、または受信者のユーザー ID だけ — SDK は署名する前に正規化します。グループ ID（`g` プレフィックス付き）はそのまま渡されます。
```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)
```
```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);
```
```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)?;
```
```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
```
```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);
```
```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);
```
***
## メディアストリーム
テキストで使用したのと**同じ**会話鍵でファイルバイトを暗号化し、Chat メディア API 経由でアップロードし、`encrypt_message` で **`media_hash_key`** を添付します。これは Posts メディアモデル（`expansions=attachments.media_keys`）ではありません。完全なアップロード/ダウンロードフロー: [Media](/xchat/media)。
```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)
```
```typescript theme={null}
const ciphertext = chat.encryptStream(fileBytes, rawConversationKey);
// Upload `ciphertext`; mediaHashKey comes from the upload finalize step.
const plain = chat.decryptStream(ciphertext, rawConversationKey);
```
```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)?;
```
```go theme={null}
ciphertext, err := chat.EncryptStream(fileBytes, rawKey)
plain, err := chat.DecryptStream(ciphertext, rawKey)
_ = plain
_ = err
```
```csharp theme={null}
var ciphertext = chat.EncryptStream(fileBytes, rawKey);
var plain = chat.DecryptStream(ciphertext, rawKey);
```
```java theme={null}
byte[] ciphertext = chat.encryptStream(fileBytes, rawKey);
byte[] plain = chat.decryptStream(ciphertext, rawKey);
```
### 大きなメディア向けのインクリメンタルストリーミング
大きなファイルの場合、ペイロード全体をメモリに保持するのを避けます: `stream_encryptor()` / `stream_decryptor()` は `StreamEncryptor` / `StreamDecryptor` を返し、`push(chunk)` でチャンク（約 1 MB ずつ）を供給し、最後に `finish()` を 1 回呼び出します。復号時、`finish()` は切り詰められたストリームを検出します（入力が最終フレームより前に終了した場合失敗します）ので、成功するまでプッシュ済み平文を完全とみなさないでください。
**JS/WASM のみ:** `finish()` は基盤となる WASM オブジェクトを消費して解放します — `finish()` の後に決して `free()` を呼び出さないでください（スローします）。`free()` は、finish の**前**にストリームを放棄する場合（たとえばエラー経路）のみ呼び出してください。
```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)
```
```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);
```
***
## ユーティリティ
Base64/hex ヘルパー、MIME 検出、および画像寸法は、モジュールレベルの関数（Python/JS/Rust/Go）または `ChatXdkUtilities`（C#/Java）として利用できます — 追加のライブラリを引き込むことなく添付メタデータを構築するのに便利です。
```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)
```
```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;
```
```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));
```
```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
```
```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;
```
```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;
```
***
## 重要な型
これらの概念的な型は言語をまたがって出現します（正確なフィールド名は異なります；JS はしばしば `message` のような camelCase のイベント識別子を使います）:
* **SendPayload** — `encrypt_message` およびその他の暗号化ヘルパーの戻り値: SDK 生成の **`message_id`**（署名付きイベントに埋め込まれた UUID — メッセージの `message_id` として送信し、重複排除のために保持）、`encrypted_content`、`encoded_event_signature`、署名メタデータ、`conversation_key_version`、および `should_notify`。Chat API 送信ボディにマップします。
* **PublicKeyRegistrationPayload** — add-public-key API 用の `generate_keypairs` / 公開鍵ゲッターの出力。
* **SigningKeyEntry** — 署名検証のために decrypt に渡す、または `set_signing_keys` 経由で保存する送信者の公開素材。
* **PreparedConversationChange** — 3 つの prepare メソッドの出力: 導出または渡された `conversation_id`、未加工の `conversation_key` バイト、`conversation_key_version`、`participant_keys`（`user_id`、`encrypted_key`、`public_key_version`）、および `action_signatures`（`message_id`、`encoded_message_event_detail`、`signature`、`signature_version`、`public_key_version`、オプションの `signature_payload` — 鍵変更署名では、そのペイロードが平文の鍵を埋め込んでいるため省略されます）。
* **DecryptEventsResult** — メッセージ、オプションのエラー、および抽出された `conversation_keys`。返信を引用する復号済みメッセージには `reply_preview_validation` が付与されます（[暗号化と送信ヘルパー](#encrypt-and-send-helpers) を参照）。
完全なフィールドリストについては、[chat-xdk リポジトリ](https://github.com/xdevplatform/chat-xdk) の言語スタブ（`docs/API.md`、`*.pyi`、`index.d.ts`）を使用してください。
***
## エラー
Python は通常、記述的なメッセージ付きの **`ValueError`** を発生させます（たとえば無効なパスコード）。TypeScript/JavaScript は **`Error`** をスローします。Go は `(value, error)` を返します。1 つの不正なイベントがバッチを中止しないよう、履歴には **`decrypt_events`** を優先してください；部分的な失敗については errors コレクションを検査します。
一部の検証エラーは**恒久的**です。署名は不変であり、イベント自体から署名済みペイロードを再構築することで検証されるため、`signature missing or no matching signing key` や ECDSA 不一致で失敗する古いイベントは、将来のすべてのロードで失敗します — 再試行、鍵の更新、または API 呼び出しでは治せません。これらはトゥームストーンとして扱い、一時的なエラーとしないでください。会話鍵をローテーションすると、その時点からクリーンで検証可能な履歴が始まります。
***
## 次のステップ
Chat XDK を Chat API に接続する
ストリーム暗号化とメディア REST
Webhook とアクティビティ配信
よくある失敗