{"library":"matrix-appservice","title":"Matrix Application Service Framework","description":"matrix-appservice is a Node.js framework designed to facilitate the creation of Matrix application services. It provides a web framework agnostic way to quickly set up performant services that can interact with a Matrix homeserver. The current stable version is 4.0.1, released in April 2026. The project maintains a roughly annual major release cadence, primarily driven by updates to Node.js version support and occasional API adjustments. It differentiates itself from more fully-featured SDKs like `matrix-appservice-bridge` by offering a more minimalist, flexible foundation for building application services, focusing on core communication patterns rather than higher-level bridging abstractions.","language":"javascript","status":"active","last_verified":"Sun Apr 19","install":{"commands":["npm install matrix-appservice"],"cli":null},"imports":["import { AppService } from 'matrix-appservice'","import { AppServiceRegistration } from 'matrix-appservice'","import { AppserviceHttpError } from 'matrix-appservice'"],"auth":{"required":false,"env_vars":[]},"quickstart":{"code":"import { AppService, AppServiceRegistration, AppserviceHttpError } from 'matrix-appservice';\nimport * as fs from 'node:fs';\n\n// Step 1: Generate an app service registration file (only needed once)\nconst reg = new AppServiceRegistration();\nreg.setAppServiceUrl('http://localhost:8010');\nreg.setHomeserverToken(AppServiceRegistration.generateToken());\nreg.setAppServiceToken(AppServiceRegistration.generateToken());\nreg.setSenderLocalpart('example-appservice');\nreg.addRegexPattern('users', '@example-.*', true);\nreg.addRegexPattern('aliases', '#example_.*', true);\nreg.setProtocols(['exampleservice']); // For 3PID lookups\nreg.setId('example-service');\n\nconst registrationFilePath = 'registration.yaml';\nreg.outputAsYaml(registrationFilePath);\nconsole.log(`Generated registration file: ${registrationFilePath}`);\n\n// Step 2: Run the app service\nconst as = new AppService({\n  homeserverToken: process.env.HOMESERVER_TOKEN ?? 'your_homeserver_token_here',\n  appServiceToken: process.env.APPSERVICE_TOKEN ?? 'your_appservice_token_here'\n});\n\nas.on('type:m.room.message', (event) => {\n  console.log(`Received message from ${event.sender}: ${event.content.body}`);\n  // Handle the incoming message\n});\n\nas.onUserQuery = async function(userId) {\n  console.log(`Received user query for: ${userId}`);\n  // Example: Validate or create the user\n  if (userId.startsWith('@baduser-')) {\n    throw new AppserviceHttpError(\n      {\n        errcode: 'M_FORBIDDEN',\n        error: 'User query or creation failed for this user ID.'\n      },\n      403\n    );\n  }\n  console.log(`User ${userId} can be created or queried.`);\n  // In a real app, you would provision the user on the AS side here.\n};\n\nas.onAliasQuery = async function(alias) {\n  console.log(`Received alias query for: ${alias}`);\n  // Handle the incoming alias query then respond\n};\n\nconst port = 8010;\nas.listen(port);\nconsole.log(`Matrix Application Service listening on port ${port}`);\nconsole.log('Ensure your homeserver is configured with registration.yaml');\n\n// Optional: Set up TLS if environment variables are present\nif (process.env.MATRIX_AS_TLS_KEY && process.env.MATRIX_AS_TLS_CERT) {\n  console.log('TLS keys found, AppService will attempt to listen with HTTPS.');\n  // AppService.listen handles HTTPS automatically if these env vars are set\n}","lang":"typescript","description":"This quickstart demonstrates how to generate a `registration.yaml` file for your application service and then how to initialize and run the `AppService` instance to listen for incoming Matrix events and handle user/alias queries. It includes an example of using `AppserviceHttpError` for error signaling and notes on optional TLS setup.","tag":null,"tag_description":null,"last_tested":null,"results":[]},"compatibility":null}