Chat: API, SDKs, and realtime

Build in-app chat using the REST API under /api/chat, the official SDKs (TypeScript, Python, Go, and others), and Socket.IO for live delivery. For Socket.IO event names and payloads, see Socket.IO: Chat.

When to use what

Authentication

Use the same org or project JWT or API key (where the operation allows it) as other project-scoped APIs. See Authentication overview and the security schemes in the OpenAPI document.

Base path

All paths below are prefixed with:

/api/chat

Endpoints

Org-level usage limits (for example channels per project or message volume) may return 403 when exceeded.

Message types

Supported type values: text, image, video, audio, file, location, contact, system (system messages are created by the platform).

End-to-end encryption (E2EE)

The platform does not decrypt E2EE message bodies. It validates and stores opaque base64 ciphertext and optional metadata (scheme, version, nonce, etc.). Cryptography belongs in your clients (web, mobile, or desktop).

Register your public key

Before others can encrypt to you, upload an identity public key (format is opaque to the API; typically base64):

PUT /api/chat/projects/{projectId}/me/chat-e2ee-key
Content-Type: application/json

{
  "identityPublicKey": "<base64>",
  "keyVersion": 1
}

keyVersion is optional; if omitted, the platform increments the previous version.

Fetch participant keys

Participants in a chat can retrieve public keys for key agreement or group key setup:

GET /api/chat/projects/{projectId}/chats/{chatId}/e2ee/participant-keys

Response data is an array of { userId, identityPublicKey, keyVersion, updatedAt }.

Send an E2EE text message

• type must be "text".
• Send e2ee.ciphertext (base64) and optional fields (version, scheme, nonce, ephemeralPublicKey, senderKeyId).
• Do not send plaintext in content for E2EE sends; the API expects either plaintext content or a full E2EE payload.
• A common default scheme name is mudbase-e2ee-v1; you can version your own format with e2ee.scheme.

Stored messages include isE2ee: true, e2ee: { ... }, and empty plaintext in content.text where applicable.

Edit an E2EE message

Use PATCH .../messages/:messageId with a new e2ee object (same shape as send). Plaintext content edits are rejected for E2EE messages, and vice versa.

Limits

Decoded ciphertext per message is capped (on the order of 64 KiB). Split large payloads across messages or use attachments if your product allows it.

Webhooks and automation

For automation that reacts to new messages, webhook or function payloads for E2EE traffic may omit plaintext (content null, isE2ee: true, scheme/version only). Treat any ciphertext in payloads as highly sensitive.

Realtime (Socket.IO)

Use the Chat (Socket.IO) doc for client events (chat:join, message:send, …) and server events (message:new, message:edited, …).

API reference

Open the API reference, filter by the chat tag, or explore operations in the OpenAPI download. Generated SDKs mirror these operations under their respective modules.