MatChat — integration reference

1. Your tenant

A tenant is issued by the operator of the deployment and is what separates your rooms, your participants and your quota from everyone else's. It has four parts.

Neither the secret nor the API key may reach a browser. Both hand out room creation and moderator tokens to whoever reads the page.

2. Embedding the widget

The widget is a custom element. Load the script once and place the element wherever the chat belongs; it fills the height of its container, so give that container one.

<script src="https://matchat.space/widget/matchat.js"></script>

<div style="height: 620px">
  <mat-chat
    room="match-12345"
    token="<participant token from your backend>"
    api="https://matchat.space"></mat-chat>
</div>

All four are live: changing token reconnects with the new identity, which is how you move a reader to a writer after they sign in.

An iframe instead

When the page cannot load third party script, embed the widget page itself. It accepts the same values as query parameters.

<iframe src="https://matchat.space/widget/index.html?room=match-12345&token=..."
        style="width:100%;height:620px;border:0"></iframe>

3. Participant tokens

Reading can be open to guests; writing always needs a token. A token says who the participant is and what they may do, and your backend is the only thing that decides that — the chat never authenticates anybody itself.

In production: sign it yourself

The token is a JWT signed with your tenant secret using HS256. No call to the chat is involved, so minting one costs your backend nothing.

import { createHmac } from 'node:crypto';

const b64 = (value) => Buffer.from(JSON.stringify(value)).toString('base64url');
const now = Math.floor(Date.now() / 1000);

const head = b64({ alg: 'HS256', typ: 'JWT' });
const body = b64({
  sub:  'u-42',            // your user id, required
  nick: 'Alice',           // shown in the room
  role: 'user',            // user | moderator | admin
  app:  'demo',            // your tenant id
  room: 'match-12345',     // optional: locks the token to one room
  iat:  now,
  exp:  now + 7200,
  iss:  'matchat',
});

const signed = `${head}.${body}`;
const sig = createHmac('sha256', TENANT_SECRET).update(signed).digest('base64url');
const token = `${signed}.${sig}`;

While prototyping: ask the deployment

Convenient for a stand and never for production, because it needs the API key of the tenant.

POST /v1/admin/tokens
X-API-Key: <apiKey>
Content-Type: application/json

{ "userId": "u-42", "nick": "Alice", "role": "user",
  "roomId": "match-12345", "ttlSec": 7200 }

200 → { "token": "eyJhbGciOi...", "expiresAt": 1788600000000 }

ttlSec defaults to two hours. expiresAt is in milliseconds, like every timestamp in this interface.

4. Rooms and their rules

A room is a topic, not a conversation between two people: everyone in it sees the same messages. Create it before the first participant arrives, from your backend.

POST /v1/admin/rooms
X-API-Key: <apiKey>
Content-Type: application/json

{ "id": "match-12345",
  "title": "Team A vs Team B",
  "topic": "Premier League, round 4",
  "status": "live",
  "settings": { "slowModeSec": 0, "maxMessageLength": 300 } }

201 → the full room

topic is the only required field. Omitting id derives one from the topic. Sending the same id again updates the room rather than failing, which makes the call safe to repeat when a match page is opened twice.

A partial settings object is merged over the rules in force, so a call that changes one field leaves the rest alone.

Status

scheduled, live, paused, closed. Only live accepts messages; the others keep the room readable. Change it with PATCH /v1/admin/rooms/{id}.

Service messages

Events of your own product belong in the room as service messages: a goal, half time, a delay. They are not written by a participant and are not rate limited.

POST /v1/admin/rooms/match-12345/system
X-API-Key: <apiKey>

{ "text": "Goal! Team A scores. 1 : 0", "kind": "goal" }

201 → the message, as participants receive it

5. Appearance

The widget carries no design opinion beyond its layout: colours, spacing, radius and typography come from you. Store a theme with the room and every participant gets it, or pass the theme attribute to override it on one page.

PUT /v1/admin/rooms/match-12345/theme
X-API-Key: <apiKey>

{ "bg": "#ffffff", "surface": "#f4f6f8", "text": "#0b1020",
  "accent": "#1a7f37", "radius": "12px", "font-family": "Inter, sans-serif" }

Each key becomes a CSS custom property named --mc-<key> inside the widget, so anything the browser accepts for that property is accepted here. Unknown keys are ignored.

The theme editor writes exactly this call and shows the result live.

6. Moderation

Moderation is done with a participant token whose role is moderator or admin — not with the API key. That is deliberate: a moderator acts from a browser, and the key must never be there.

Every one of these reaches all participants immediately, on every node: a deleted message disappears from open pages, and a muted participant is told for how long.

7. Your own interface

The widget is one client of a protocol that is open to you. Build your own and you still get history, presence, moderation and the same rules.

Reading over HTTP

The stream

const ws = new WebSocket(
  'wss://matchat.space/v1/ws?room=match-12345&token=' + token
);

The first frame is hello: who you are, the room, the recent history and the count online. After that the stream carries what happens.

clientMessageId is worth setting: a retry after a lost connection carries the same one and is not delivered twice. The answer comes back as ack with the identifier the message actually got.

The API only client is a working example of exactly this, in about a hundred lines.

8. Refusals and limits

A refusal is never silent. Over HTTP it is a status with {"error":"<code>"}, over the stream an error event with the same code, and the codes are stable enough to switch on.

What the limits actually are

Moderators and administrators are exempt from the per participant limits.

9. Constraints