Bot Setup

The easiest way to set up is with the build tools. With node 6+ installed, run:

npm install -g @exoplay/exobot-build
mkdir exobot
cd exobot
exobot new bot
npm start

This will set you up with an npm package with the basics installed, create a git repo, generate a sample configuration file, and pre-build a bot.

There are two primary ways to configure Exobot: you can either use a static configuration file with configuration built-in, or you can lean on automatically-loaded environment variables to configure your bot.

The Environmental Way

Environment-based setup automatically parses environment variables based on plugin name. For example, if in your configuration file, you have a plugin named giphy and it has a configuration parameter called token, you would set an environment variable called GIPHY_TOKEN to the proper value.

The Explicit Way

Exobot is configured in its constructor, which takes two arguments - a bot name (a required string), and an options object.

The bot name is used for commands - if your bot's name is 'exobot', it will respond to commands beginning with 'exobot'. You'll want this to match the name used in your chat service (so if its name is actually 'DEATHBOT_9000' in Slack, you should call it that here too, or people may be confused.)

The options object contains all other configuration - such as a list of plugins and chat service adapters, log levels, and data encryption keys.

  • alias - an additional way to trigger exobot commands. '/', ';', or 'hey bot', for example.
  • adapters - an array of initialized chat adapters, such as slack, discord, or twitch. exobot also comes with a shell adapter for playing around in your terminal.
  • plugins - an array of initialized plugins, such as giphy or points. exobot also comes with help and greetings plugins as examples.
  • readFile and writeFile - functions called when the in-memory json db is saved. By default, this writes a json file to cwd/data/botname.json, but you could also override the default local file storage to use s3 with @exoplay/exobot-db-s3.
  • dbPath - if you're using local file storage, you can set where to save. Defaults to cwd/data/botname.json.

Exobot has a robust group-based permissions model. By default anybody can access commands, but you can use the built-in Permissions plugin to lock down the bot and whitelist commands to users in specific groups.

Running exobot plugin help permission will explain the commands used to manage permissions. The general idea is that each command in exobot will have a category, such asuptime.uptime, and you can whitelist commands for each group, and add people to one or more groups. This keeps commands safe in public channels, such as locking down the ability to schedule events to moderators.

Building on top of the permissions sytem, you can also attach the HTTP adapter to exobot to allow it to receive messages over HTTP. Run exobot plugin help webhook to find out about the specific commands. You'll basically create new "users" for each webhook, and give each usr a group - so that each webhook only has access to the commands you explicitly give it.

Configure the HTTP adapter for Exobot (done by default when using the build tools) to use webhooks, and call it by accessing the server exobot is running at, at the port specified, with ?token, ?userid, and ?message passed in. This will run the contents of ?message through plugins and possibly respond in configured channels.