API & SDK

Everything the Refract.Chat apps do goes through the same HTTP API and real-time socket, so anything they can do, your code can do too: as a person, or as a bot.

The API isn't stable yet. Expect changes between releases while Refract.Chat is a work in progress.

The SDK

@refractchat/sdk is the TypeScript client the apps themselves use. It runs in browsers and Node.js, and includes:

• ApiService: every REST endpoint, grouped by area (api.auth, api.server, api.channel, api.message, …), with typed requests and responses.
• SocketManager: the real-time connection, which re-attaches your listeners when it reconnects.
• Types and helpers: every API and event type, plus the permission maths, mention parsing and other logic the apps share.

The SDK isn't on npm yet. It's the sdk/ package of the Refract.Chat repository: build it with yarn --cwd sdk install && yarn --cwd sdk build, then depend on it by path ("@refractchat/sdk": "file:../sdk").

Every class, method and type is listed in the SDK reference, generated from the SDK's source.

import { ApiService } from "@refractchat/sdk";

const api = new ApiService();
api.setBaseURL("https://chat.example.com/api/v1");

const { token, refreshToken, user } = await api.auth.login("alice@example.com", "password");
api.setToken(token!);

const { servers } = await api.server.getUserServers();

The package also exports a ready-made instance, api, which uses the relative base URL /api/v1, as the web app does.

The HTTP API

• Base URL: https://<instance>/api/v1.

• Authentication: Authorization: Bearer <token>, with a person's session token or a bot token.

• Requests: JSON, up to 100 KiB. Files are uploaded separately, as raw bytes (POST /api/v1/media/pending, or api.media.uploadMediaFile), up to the instance's file size limit.

• Responses: JSON, with success: true and the data, or success: false and an error:

  {
    "success": false,
    "error": { "code": "channel_not_found", "message": "That channel no longer exists or is unavailable to you." }
  }

  error.code is stable and meant for code to check; message is for people. The SDK rejects with this { code, message } object.

• Rate limits: 429 when a limit is reached. Back off and retry.

Signing in

POST /api/v1/auth/email/login (api.auth.login) returns a short-lived session token and a longer-lived refreshToken. Use the token for requests, and exchange the refresh token for a new one with POST /api/v1/auth/email/refresh (api.auth.refreshSession) when it expires.

The response may instead carry an interstitial, such as an email address to verify or an admin's approval to wait for, with a loginToken to retry with once that's done. A web sign-in lasts 30 days.

Signing out (POST /api/v1/auth/logout with the refresh token, api.auth.logout) ends that one sign-in. Changing the password, or an admin denying the account, ends every sign-in at once.

Real-time events

New messages, people joining and leaving, presence, calls and the rest arrive over Socket.IO, at the path /api/socket.io on the instance:

import { SocketEventType, SocketManager } from "@refractchat/sdk";

const socket = new SocketManager();
socket.on(SocketEventType.CHANNEL_MESSAGE_ADDED, ({ message }) => {
  console.log(`#${message.channelId}: ${message.content}`);
});
socket.ensureConnected("https://chat.example.com", token);

on returns a function that removes the listener. Register listeners before or after connecting: SocketManager keeps them across reconnects. SocketEventType lists every event, and its payload types are in the SDK reference.

Where to next

• Bots: a server bot with its own token.
• SDK reference: every endpoint method and type.