Choosing Between Gitter’s Legacy REST API and Matrix API for Bot Development

Decision Context

When building a bot or integration that talks to Gitter, you must decide whether to use the legacy REST API (api.gitter.im) or the newer Matrix API that powers Gitter’s current homeserver. The choice determines authentication flow, feature set, and long‑term viability.

Comparison Table

Aspect	Legacy REST API	Matrix API (Gitter homeserver)
Authentication	OAuth2 with personal or app tokens scoped to a Gitter user	Matrix access token from a Matrix account; devices can be registered via SSO
Real‑time events	Faye/Bayeux over WebSocket; limited to room‑specific streams	/sync long‑poll or SSE; full state delta and lazy‑loading support
Feature set	Room messages, user info, webhooks, basic streaming	Rooms, threads, reactions, spaces, end‑to‑end encryption (E2EE), federation
Maintenance status	Maintenance mode; GitLab announced shutdown in 2025	Actively developed; new features added regularly
Rate limits	~100 requests/min per token	~30 requests/sec per IP by default; configurable per homeserver
Bridge compatibility	Direct Gitter rooms only	Gitter rooms exposed as Matrix aliases (#room:gitter.im)

Trade‑offs

The legacy API is simpler to bootstrap for one‑off notifications but lacks modern chat features. Matrix offers richer interactions (threads, reactions, E2EE) and future proofing, but requires handling Matrix state and cryptographic sessions if the room is encrypted. Bots using Matrix will see Matrix user IDs instead of Gitter usernames; mapping requires a profile lookup via the Matrix API.

Concrete Validation: Matrix Bot Example

Below is a minimal TypeScript bot using the matrix-bot-sdk that joins a bridged Gitter room and echoes a command. Replace YOUR_MATRIX_ACCESS_TOKEN with a token generated in Element (app.element.io) under Settings > Security > Personal Access Tokens.

import { MatrixClient, SimpleFsStorageProvider, AutojoinRoomsMixin } from "matrix-bot-sdk";

const homeserverUrl = "https://matrix.gitter.im";
const accessToken = "YOUR_MATRIX_ACCESS_TOKEN";
const storage = new SimpleFsStorageProvider("bot.json");
const client = new MatrixClient(homeserverUrl, accessToken, storage);
AutojoinRoomsMixin.setupOnClient(client);

client.on("room.message", async (roomId, event) => {
  const content = event.content as any;
  if (content.msgtype !== "m.text") return;
  if (content.body === "!ping") {
    await client.sendMessage(roomId, { msgtype: "m.text", body: "Pong! Matrix bot active." });
  }
});

client.start();

Steps to run:

1. Invite the bot’s Matrix user to a Gitter room that is bridged (e.g., #project:gitter.im) via the Gitter web UI.
2. Execute npm i matrix-bot-sdk and run the script with node bot.js.
3. In the Gitter web UI, type !ping and observe the reply in both Gitter and Element.
4. Check the console for 401 or 403 errors if the message does not appear; these indicate token or permission issues.

Verification Checklist

• Confirm the legacy API docs redirect to Matrix docs to verify deprecation.
• Generate a Matrix PAT in Element and test /sync manually with curl -H "Authorization: Bearer <token>" https://matrix.gitter.im/_matrix/client/r0/sync?timeout=30000.
• Join a bridged room and send a formatted message; ensure it appears in both UIs.
• Monitor rate‑limit headers (X-Rate-Limit-Remaining) when making API calls.

In summary, for any new production bot or integration, target the Matrix API. The legacy REST API is only suitable for legacy scripts that can tolerate imminent shutdown.