Passport Bot

A slack bot that handles user inquiries by command or mention.

Configuration

Create the file src/config/local.ts that will hold the settings of the project. Take a look at IConfig interface to see available options. You will probably need to override the following fields:

• db.master (if your commands use direct DB interactions)
• db.replicas
• db.cache
• slack.botToken (see how to get Slack secrets below)
• slack.appToken
• slack.signingSecret
• slack.appId
• internalApi.url (if your command uses the internal API)
• internalApi.key

Registering your debug app

To prevent interfering with the production app, you'll need to create your custom Slack app and configure it in a proper way.

1. Go to [https://api.slack.com/apps](your Slack space) and click the button to create a new app.
2. On the first step choose either your own (preferrable) or Passport workspace (in this case see the next section on proxy commands). Note that even if you use your own workspace, you still need a separate app as you may change the manifest during experiments. The production app shouldn't suffer from any accidental changes.
3. Choose the option to create an app from manifest and paste contents of the manifest.example.json file from this repo to the textarea as a template (don't hit the button yet).
4. Change your app name, bot name, and the proxy command name. You must use this custom proxy command when installing the app to Passport workspace. With your own workspace, you may not set it and launch actual commands your want to try without any prefix. However, the proxy command may still be more convenient as it allows you not to change the manifest when the set of commands gets modified.
5. Click Next and then approve your app permissions. The app should be created now and you will be redirected to the app settings.
6. Click the button Install to Workspace and finish the installation.
7. Copy to your local config the signing secret.
8. (optional) From the same section you can copy the application id to your config. You'll need it for managing manifests through scripts.
9. Find the section "App-Level Tokens" and generate an app token. Copy it to your local config.
10. Go to the page "OAuth & Permissions" and copy the bot token to your config.

Configuring a proxy command

To debug your app in Slack without interfering with the production app, you should use the proxy command. It looks as a prefix to normal commands and serves as an entry point. This will also save you from updating the manifest each time you add a new command as it will basically contain just the proxy command all the time.

In the case of the proxy command called /proxy, the command /help turns into /proxy /help.

To configure the command, you should put the same string starting with slash

1. to the app manifest
2. to the local config under proxyCommand key

Configuring app manifesting (optional)

When you add/remove/rename some command or want to modify its description there are two ways. You can go to your app page and manually upload the new version of the manifest file. Alternatively, you can use npm scripts for syncing your app manifest with Slack.

As a prerequisite for the latter, you need to setup a redis connection overriding the sharedCache config property or simply launch a local Redis on the default port (these are default settings).

Another requirement is setting the slack.appId value in your local config. It is only necessary for this script-based manifest management.

Next, you need to go to your configuration token page in Slack (it's account-level data outside of app settings). Generate if needed and copy the access and refresh tokens.

Run the following command and provide the tokens as script parameters:

# e.g., npm run init-tokens -- xoxe.xoxp-1-AAA... xoxe-1-BBB...
npm run init-tokens -- <access_token> <refresh_token>

This will set up Redis with initial token values. Normally you need to do it only once, the tokens will be rotated automatically from this point when you run the manifest syncing script.

The manifest syncing script takes the current manifest, replaces the slash commands section with the actual content automatically generated from the commands you have. If you have a proxy command set, the section containing it will be the only one in the generated manifest.

From now on you can synchronize your manifest by running:

npm run sync-manifest

Installation & Running

# Install dependencies
npm i

# Run application in dev mode
# (this will watch for changes and automatically restart the app)
npm start

Quick start

You can find a ready command example in the examples folder. It already has all the required MVC structure, argument validation, interaction with an external data source and a fancy output. The best thing is, however, that you may use it to kickstart your development! The following command will simply copy the example to your source folder and it should be ready to go:

npm run chuck

Provided you already have your proxy command configured as my-proxy-command, you can now ensure your app is rebuilt, go to Slack, enter the following message: /my-proxy-command /chuck and see an awesome joke!