Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Build Status Coverage Status Total Contributors

Doorman is a friendly, automated helper for managers of large online communities. Simple to install and easy to configure, Doorman can welcome new users, guide them through onboarding flows, and help keep track of important projects and events using a robust-plugin API.

Quick Start

  1. Fork (optional) and clone: git clone
  2. Run cp config/index.json.example config/index.json & add your auth tokens
  3. Run npm install
  4. Run npm start


Doorman comes pre-configured with support for multiple chat platforms, including Slack, Discord, and Matrix. Adding support for additional services is easy — inspect the types/service.js prototype for a list of required methods. Feel free to submit a Pull Request to add support for your favorite services!


Doorman behaviors range from simple triggers (commands prefixed with ! located anywhere within a message) to complex applications which communicate through a simple message-passing API. The trigger prefix is configurable using the trigger keyword in the configuration file.

Plugins are automatically loaded when included in config/index.json, under the "plugins" section, or manually by calling doorman.use(). Doorman will look first in the ./plugins folder for the named plugin (most useful for simple prototyping), then will attempt to load from NPM using the doorman-* naming pattern. Plugins may be published to the NPM registry and installed via npm install as usual.

Official Plugins

List of external plugins for you to include with your installation (if you wish):

Simple Plugins

Ping-Pong Example Plugin, ./plugins/ping.json

  "ping": "Pong!"

To use this plugin, add ping to your configuration file and Doorman will respond to any messages that include !ping with a simple Pong! response.

Complex Plugins

In addition to simple !triggers, Doorman can call functions to compute responses, or even instantiate external applications for managing long-running processes.

Function Call Example Plugin, ./plugins/erm.js

const erm = require('erm');
const plugin = {
  erm: function (msg) {
    return erm(msg);

module.exports = plugin;

Instantiated Example Plugin

function MyPlugin (config) {
  // config will be passed from `./config/index.json` based on the plugin name

MyPlugin.prototype.start = function () {
  console.log('Hello, world!');

module.exports = MyPlugin;

Manually Loading Plugins

To load the plugin, simply call doorman.use() on the plugin you wish to add. Multiple !triggers can be added, each as key => value mappings provided by the plugin.

const config = require('./config');
const plugin = { fancy: 'Mmm, fancy!' };

const Doorman = require('doorman');
const doorman = new Doorman(config);


Message Passing API

Doorman emits events like any other EventEmitter, using a simple router for distinguishing between messages, users, and channels on various services. This allows Doorman to stay connected to multiple networks simultaneously — a feature we rely on in our flagship project, Fabric!

General Message Format


Doorman uses the Fabric Messaging Format to uniquely identify objects within the system. Each object has an id field, which usually takes the following format:


For example, a user event might emit the following object:

  "id": "slack/users/U09HF4JLV",
  "@data": {
    "id": "U09HF4JLV"

Users (the user event)

Channels (the channel event)

Messages (the message event)

State Management (the patch event)


Configuring Doorman will typically require the creation of a "bot" user on the platform of choice, and the use of a security token to authenticate requests.


Register a user for your bot, then collect the "Access Token" from the user's settings — you will need to use the "click to reveal" feature to display the token.

Place the token into config/index.json under the matrix index, and specify user and authority:

  "matrix": {
    "token": "place-the-token-here",
    "user": "",
    "authority": ""


In your team's workspace, browse to "Apps", "Custom Integrations", "Bots", and finally "New configuration". Place the "API Token" into config/index.json:

  "slack": {
    "token": "xoxb-0000000000000-somelongstring..."


@naterchrdsn will need to fill this out. :)


Documentation can be generated by running npm run make:docs — this will output an HTML-formatted copy of the API to docs/, which can be served with (if installed!) http-server docs or simply opened in your browser.


Say hello to Doorman, your made-to-fit community manager. Simple API, feature-rich plugins, and more.








No packages published