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 of them are live: changing token reconnects with the new identity, which is how you move a reader to a writer after they sign in, while changing lang keeps the connection and only affects what is translated next.

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.

GET /v1/admin/rooms answers with every room of your tenant and the rules in force, which is what a dashboard of your own needs.

Removing a room

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

204 → gone, along with its history, reactions and bans

Everyone reading the room is told and disconnected, on every node, so nobody is left holding a socket to a topic that no longer exists. The identifier is free again afterwards and comes back empty, with the ordering counter starting over.

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

Out of the box the widget is dark and frosted: translucent panels over a near black background, a hairline catching light along their top edge and a single accent colour. Every part of that is a key you can replace — colours, spacing, radius, blur and typography. 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. Translation

A message can be shown in the language of whoever is reading it. In the widget that is the globe on a message: it puts the translation under the original and the original stays, one press away. The language is the lang attribute of the element, or the language of the browser when you leave it out.

POST /v1/rooms/match-12345/messages/mtoo9f1c8ab2/translation
Authorization: Bearer <participant token>
{"to": "ru"}

200 → {
  "messageId": "mtoo9f1c8ab2",
  "to": "ru",
  "text": "\u043a\u0430\u043a\u043e\u0439 \u0433\u043e\u043b \u0441 \u0443\u0433\u043b\u0430",
  "sourceLang": "en",
  "translated": true,
  "cached": true
}

A reader who may read the room may translate it, so a guest of a room with allowGuestRead needs no token here. to is a language code such as ru, de or pt-BR; anything else is refused as bad_language rather than guessed at.

translated: false means there was nothing to translate — a row of emoji, a scoreline — and text is then the original. Say so rather than showing the same words twice.

What makes any of this affordable is that the answer is cached by the text and not by the message: the first reader pays, every reader after them is served free, and the same chant sent by ten thousand people is one translation. cached tells you which of the two happened.

The whole room at once

A room can also translate as it goes, with nobody pressing anything. Turn it on in the rules and name the languages of your audience:

PATCH /v1/admin/rooms/match-12345
X-API-Key: <your api key>
{"settings": {"autoTranslate": true, "autoTranslateLangs": ["en", "es"]}}

Languages are base codes without a region — en, not en-GB — and at most five of them: the cost of a room is multiplied by their number. A code that is not one is refused as bad_language, and switching this on where the deployment has no provider is refused as translation_off, rather than leaving you with a room that looks configured and does nothing.

Each connection is then sent the one language it asked for, in a translations frame that arrives a few seconds after the messages it belongs to — the messages of a moment are collected and translated together, and a provider takes a second or three over a batch. The language comes from the handshake:

wss://matchat.space/v1/ws?room=match-12345&token=<token>&lang=en

← {"type":"translations","translations":[
     {"lang":"en","items":[
       {"messageId":"mtoo9f1c8ab2","text":"the ref is blind","source":"ru"}
     ]}
   ]}

Translations are a separate frame rather than part of the message, because they cannot be part of it: the message is delivered the instant it is accepted and the translation comes back from a provider seconds later. Put it under the original and keep the original: a machine translation is a reading aid, and what was actually said has to stay available, to the reader and to a moderator. The widget does this on its own; nothing to build.

A reader who changes language sends {"type":"lang","lang":"es"} and keeps their connection. There is no need to rejoin, and rejoining would refetch the history and lose their place in it. A language the room does not translate into simply matches nothing.

Messages with nothing to translate never reach a provider, repeated text is paid for once per window, and a room sending faster than the provider answers drops the translations it cannot keep up with rather than falling behind. The chat itself is never held up for a translation.

Languages do not queue behind each other: each is asked for separately and they are asked for at once, so a room in five languages is translated as quickly as a room in one. It is why five is the limit — the delay stays put as languages are added, and only the bill grows.

What it costs

Translation is the one thing here billed per use, and the arithmetic decides the design. On request, the spending follows what is actually read, which is why the control exists at all. Automatically, it follows what is written, multiplied by the number of languages: a busy match room is a few dollars an hour per language, a quiet one is cents. Both are bounded by the caps below, so neither can surprise the operator.

What it costs you to switch on

Nothing in your integration: the provider and its key belong to the deployment, not to you. If translation_off comes back with status 501, this deployment has no provider configured — ask the operator. With status 409 it is the room: allowTranslation is off.

8. 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.

9. 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.

10. Constraints