Quick start
First realtime message in six lines in a development environment; production adds one server route.
1. Create an app
Sign in with your email and create an app (the API calls it a project). ByoTalk creates two environments, development and production, each with its own environment ID (env_...) and secret key. The dashboard's Quick start page shows these snippets with your real environment ID filled in, and the Playground lets two test users chat in the browser without code.
2. Install
npm i byotalk
One package, subpath exports: byotalk (browser, React Native, Node 22+), byotalk/react-native, byotalk/server and the npx byotalk CLI (database drivers not included: see Bring your own database).
Native apps: iOS and Swift, Android and Kotlin, Flutter and Dart.
3. Connect and send (development)
Development environments accept dev tokens, so you can start without a backend.
import { Chat } from "byotalk";
const chat = new Chat({ env: "env_dev_2f8k", token: Chat.devToken("alice") });
await chat.connect();
const dm = await chat.conversations.direct("bob");
dm.on("message.new", (m) => console.log(m.senderId, m.text));
await dm.send({ text: "Hello Bob" });
Users are created on first connect. Development uses Managed storage, so there is nothing to configure.
3b. React Native
npm i byotalk react-native-get-random-values
# optional: @react-native-community/netinfo (reconnect when the network returns), react-native-mmkv or
# @react-native-async-storage/async-storage (unsent messages survive a restart)
import "react-native-get-random-values"; // first, in your entry file: Hermes has no crypto.getRandomValues
import { createChat, mmkvPersistence } from "byotalk/react-native";
const chat = createChat({ env: "env_…", token: getToken, persistence: mmkvPersistence() });
await chat.connect(); // also starts the AppState/NetInfo listeners; disconnect() removes them
Message ids are UUIDs made with crypto.getRandomValues. Without the polyfill createChat() throws an error naming it (on Expo you can instead set globalThis.crypto = { getRandomValues } with getRandomValues from expo-crypto). mmkvPersistence() works with react-native-mmkv v2, v3 and v4, or pass your own instance: mmkvPersistence(storage). On sign-out call await chat.clearLocalData() then await chat.disconnect(); create a new chat for the next user.
4. Production
Dev tokens are always disabled in production. Add a token route to your existing backend with byotalk/server; it signs tokens locally with your secret key.
// server
import { ChatServer } from "byotalk/server";
const chatServer = new ChatServer({ secretKey: process.env.BYOTALK_SECRET_KEY! });
app.get("/chat-token", requireLogin, async (req, res) => {
await chatServer.users.upsert({ id: req.user.id, name: req.user.name, imageUrl: req.user.avatarUrl });
res.json({ token: chatServer.createToken(req.user.id, { expiresIn: "1h" }) });
});
// client
const chat = new Chat({
env: "env_2f8k",
token: () => fetch("/chat-token").then((r) => r.json()).then((d) => d.token),
});
A function token is called again before the token expires.
5. Choose storage
- Managed: messages stay in our database, encrypted. Nothing to set up.
- Your own database: PostgreSQL, MySQL/MariaDB, MongoDB or an HTTP endpoint becomes the permanent record. See Bring your own database.
- Media: connect Cloudinary, an S3-compatible bucket or Azure Blob. See Media storage.
Next
- Webhooks to react to messages on your server
- REST API overview
- Realtime protocol
- Data location statement