Matrix Application Service framework in Node.js
  • TypeScript 94.6%
  • Shell 5.4%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Andrew Ferrazzutti f332ccea8f 4.1.0
2026-08-10 01:37:41 -04:00
.github Revert to using ubuntu-latest 2026-08-04 09:52:12 -04:00
changelog.d 4.1.0 2026-08-10 01:37:41 -04:00
scripts Add scripts/check-newsfragment 2022-07-20 17:07:57 +01:00
src Address review: spec link v1.13 and richer receipt test fixtures 2026-07-03 00:41:03 +07:00
test Address review: spec link v1.13 and richer receipt test fixtures 2026-07-03 00:41:03 +07:00
.eslintrc Fix linting 2020-07-22 13:54:38 +01:00
.gitignore Add TypeDoc 2020-09-04 11:46:36 +01:00
.node-version Drop Node 22, support Node 25, update deps (#74) 2026-03-19 21:42:49 -04:00
.npmignore Add TypeDoc 2020-09-04 11:46:36 +01:00
CHANGELOG.md 4.1.0 2026-08-10 01:37:41 -04:00
CONTRIBUTING.md Update docs 2022-07-20 16:59:57 +01:00
LICENSE Initial commit 2015-02-27 22:32:03 +00:00
package.json 4.1.0 2026-08-10 01:37:41 -04:00
pyproject.toml Towncrier bits 2020-07-22 13:50:19 +01:00
README.md Add missing command in example registration script 2023-07-19 16:58:30 -04:00
tsconfig.json Drop Node 22, support Node 25, update deps (#74) 2026-03-19 21:42:49 -04:00
yarn.lock Touch up lockfile 2026-08-10 00:56:56 -04:00

matrix-appservice-node

This is a Matrix Application Service framework written in Node.js.

This can be used to quickly setup performant application services for almost anything you can think of in a web framework agnostic way.

If you are looking for a more fully-featured SDK for creating bridges, you may want to check out matrix-appservice-bridge instead.

Example

To create an app service registration file:

const { AppServiceRegistration } = require("matrix-appservice");

// creating registration files
const reg = new AppServiceRegistration();
reg.setAppServiceUrl("http://localhost:8010");
reg.setHomeserverToken(AppServiceRegistration.generateToken());
reg.setAppServiceToken(AppServiceRegistration.generateToken());
reg.setSenderLocalpart("example-appservice");
reg.addRegexPattern("users", "@.*", true);
reg.setProtocols(["exampleservice"]); // For 3PID lookups
reg.setId("example-service");
reg.outputAsYaml("registration.yaml");

You only need to generate a registration once, provided the registration info does not change. Once you have generated a registration, you can run the app service like so:

import { AppService, AppserviceHttpError } from "matrix-appservice";
// listening
const as = new AppService({
  homeserverToken: "abcd653bac492087d3c87"
});
as.on("type:m.room.message", (event) => {
  // handle the incoming message
});
as.onUserQuery = function(userId, callback) {
  // handle the incoming user query then respond
  console.log("RECV %s", userId);

  /*
  // if this userId cannot be created, or if some error
  // conditions occur, throw AppserviceHttpError exception.
  // The underlying appservice code will send the HTTP status,
  // Matrix errorcode and error message back as a response.

  if (userCreationOrQueryFailed) {
    throw new AppserviceHttpError(
      {
        errcode: "M_FORBIDDEN",
        error: "User query or creation failed.",
      },
      403, // Forbidden, or an appropriate HTTP status
    )
  }
  */

  callback();
};
// can also do this as a promise
as.onAliasQuery = async function(alias) {
  console.log("RECV %s", alias);
};
as.listen(8010);

TLS Connections

If MATRIX_AS_TLS_KEY and MATRIX_AS_TLS_CERT environment variables are defined and point to valid tls key and cert files, the AS will listen using an HTTPS listener.

API Reference

A hosted API reference can be found on GitHub Pages.