poolse documentation

poolse is hosted chat and calling infrastructure. Your backend creates users and mints short-lived tokens; your apps use the poolse SDKs to send messages, place calls and receive live updates. poolse stores the data, runs the realtime connections and sends push notifications to phones.

What poolse does today

• Conversations: direct (one-to-one) and group conversations with owner, admin and member roles. See Conversations & roles.
• Messages: text, editing, deleting, reactions, replies in threads, quoted messages, @mentions and file attachments. See Messages.
• Read receipts and unread counts, with a workspace-wide setting for who can see read state. See Read receipts & unread.
• Realtime: a WebSocket that pushes new messages, edits, reactions, typing, presence and call state to connected clients. See Realtime.
• Calls and rooms: voice and video calls that ring phones, and rooms people join at will. Media runs on LiveKit. See Calls & rooms.
• Push notifications: poolse itself sends call pushes, chat notifications and missed-call notifications through Apple (APNs) and Google (FCM), using credentials you add in the dashboard. See Push notifications.
• Webhooks: signed HTTP POSTs to your backend when something happens. See Webhooks.
• Audit logs of API mutations, readable with an API key. See Audit logs.
• A dashboard for API keys, webhooks, messaging, call and push settings, usage and plan. See the Dashboard guide.

How the pieces fit

┌──────────────┐   API key (pk_live_…)   ┌──────────────┐   user token (JWT)    ┌──────────────┐
│ Your backend │ ──────────────────────▶ │  poolse API  │ ◀──────────────────── │  Your app    │
│              │ ◀── user id, token ──── │              │   REST + WebSocket    │ (poolse SDK) │
└──────────────┘                         └──────────────┘                       └──────────────┘
        ▲                                        │
        └──────────── signed webhooks ───────────┘

1. Your backend holds the API key. It creates users and mints a token for each signed-in user.
2. Your app uses the user token, which lasts one hour, for REST calls and the WebSocket. The SDK asks your backend for a new one when it needs it.
3. poolse calls your backend with webhooks, if you set them up.

The API key never goes into a browser or mobile app. A user token only works for that one user, inside your workspace.

Packages

All five packages are released together and share a version (3.1).

# Web
npm install @poolse/sdk @poolse/react @poolse/react-ui

# React Native
npm install @poolse/sdk @poolse/react @poolse/react-native @poolse/native

Upgrading from 2.x? Read Migrating to 3.0.

Where to go next

Common tasks