Quick start

Get from zero to realtime chat in a few steps. Use this page first; open the linked guides when you need more detail.

You will:

1. Register a user and mint a session JWT on your server (API key).
2. Create a room (API key).
3. Expose a session route your app can call.
4. Connect in the browser with @sendsar/chat-sdk-javascript and receive messages.

Placeholders

{API_URL} = your Sendsar API base URL, e.g. http://localhost:3001/v1.
Never put the API key (sk_…) in the browser — only the short-lived session JWT.

Terminology

Account = your Sendsar organization (one API key). In the API and codebase this is called a tenant — e.g. tenantId, PATCH /tenant/settings, socket event tenant-presence.

---

Prerequisites

• Sendsar API gateway running (local: pnpm start:dev in apps/gateway)
• Your account API key (sk_…; tenant API key in the API) and {API_URL} in your server environment

export SENDSAR_API_URL="http://localhost:3001/v1"
export SENDSAR_API_KEY="sk_your_key"

---

1. Register user & mint token (server)

Run on your backend (or curl for a smoke test):

# Upsert user (required before minting a token)
curl -s -X POST "${SENDSAR_API_URL}/users" \
  -H "x-api-key: ${SENDSAR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "id": "user_abc123", "username": "Alice" }'

# Mint session JWT for that user
curl -s -X POST "${SENDSAR_API_URL}/auth/token" \
  -H "x-api-key: ${SENDSAR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "userId": "user_abc123", "expiresIn": 3600 }'

Save the token from the response. Details: Authentication, Server setup — session flow.

---

2. Create a room (server)

curl -s -X POST "${SENDSAR_API_URL}/chat/rooms" \
  -H "x-api-key: ${SENDSAR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Quick start",
    "participants": [
      { "id": "user_abc123", "username": "Alice" },
      { "id": "user_peer_456", "username": "Bob" }
    ]
  }'

Copy the room id (UUID) from the JSON response. More examples: Server API examples.

---

3. Session route (your backend)

Add one authenticated endpoint (e.g. GET /api/chat/session) that:

1. Identifies the logged-in user in your app.
2. Calls POST {API_URL}/users then POST {API_URL}/auth/token with x-api-key.
3. Returns JSON to the client:

{
  "token": "<session-jwt>",
  "expiresAt": "2026-05-30T12:00:00.000Z",
  "apiUrl": "http://localhost:3001/v1",
  "chatUserId": "user_abc123",
  "displayName": "Alice"
}

Full samples (Node, PHP, Python, …): Server setup — session route.

---

4. Connect in the browser (client)

npm install @sendsar/chat-sdk-javascript

import Sendsar from "@sendsar/chat-sdk-javascript";

const res = await fetch("/api/chat/session", { credentials: "include" });
if (!res.ok) throw new Error("Not authenticated");

const { token, chatUserId, apiUrl } = await res.json();

const client = Sendsar.init({ apiUrl });
await client.connect({ userId: chatUserId, token });

client.joinRoom({ roomId: "PASTE_ROOM_UUID_HERE" });

client.on("new-message", (msg) => {
  console.log("New message", msg);
});

// Optional: send a message
await client.sendMessage("PASTE_ROOM_UUID_HERE", {
  parts: [{ type: "text", text: "Hello from quick start" }],
});

React / Next.js: React SDK. CDN and TypeScript: HTML & vanilla JS.

---

Verify it works

Check	How
REST	Second user sends via API or another browser tab with their own session
WebSocket	new-message fires in the console without refresh
API docs	Open API Reference (Scalar) on your gateway

---

Go deeper (when you need it)

Topic	Guide
API key vs session JWT	Authentication
Env vars, checklist, production	Server setup
Rooms, messages, curl recipes	Server API examples
Offline push	Push notifications
Signed server events	Webhooks
All REST endpoints	API Reference

---

Common blockers

Symptom	Fix
404 on POST /auth/token	Call POST /users first (why)
401 in the browser	Session route must return a fresh JWT; use connect() after login
No messages in console	joinRoom must use the room UUID; user must be a participant
403 Cannot act as another user	Client must use its own chatUserId from the session response