Create new "room services" with a classic form in a popup dialog. Just select what events and terms you want Botler to listen to and then enter what you want Botler to say when that happens.

For you advanced users, you can use regular expression for smarter phrase detection and even use captured terms in your replies.

By default, Botler's replies are rendered just like your normal messages, which means that your @@mentions and emoticons will appear as expected. You can opt-in to use HTML rendering instead if you're a fancy hypertext wizard.

Run Botler in a Docker container

This is an experimental way for you to run Botler yourself using Docker, which could be useful for "Behind the Firewall" (on-premises) Hipchat Data Center deployments. The Dockerfile and Docker Compose file help you quickly download and bundle any needed dependencies.

If you'll be running this on a deployment without access to the internet, your process will look something like this:

  1. Clone this repository.
  2. Build a container from the repository.
  3. Pass the container to your on-premises deployment using whatever process is approved by your organization.
  4. Run the container on a host within your firewall. Optionally, you may also push the image to a Docker Registry, Docker Trusted Registry, or Docker Datacenter repository.


  1. Check for port conflicts on port 3024. Botler will use this port, so you want it to be available. If you have a conflict, change the PORT variable in the docker-compose file to something else.
  2. Clone this source repository to your local machine: git clone

Build the container

  1. Change directories to the source you just cloned: cd hipchat-botler
  2. Run the following command to use the Dockerfile in this repo to build a container with the latest version of Botler. sudo docker build -t atlassianlabs/botler:latest .

Run the Botler service

  1. Run the following command to use the Docker Compose file in this repo to build the Botler service. docker-compose up -d

  2. Check the logs to make sure everything went smoothly using the following command. docker-compose logs

  3. Verify that the following URL returns a valid capabilities.json response. (Replace 'your-docker-host-fqdn' with your actual host.) http://your-docker-host-fqdn:3024/

Install Botler on your Hipchat instance

Next, make your Dockerized version of Botler available on your Hipchat service.

Note: You must be at least a room admin to install an integration in a room. Only admins can install integrations globally.

  1. Log in to your Hipchat instance.
  2. If you're using Hipchat Cloud or Hipchat Server, click the Manage tab.
  3. If you're using Hipchat Data Center, log in to the web portal and click Add-ons in the left navigation.
  4. Click Install an add-on from a descriptor URL. (It's at the very bottom of the page.)
  5. In the dialog that appears, enter the URL you used above: http://your-docker-host-fqdn:3024/ Hipchat verifies the add-on capabilities, and adds it to your deployment.


Go to a chat room and type /botler!


To get started, clone this repository and install it's dependencies.

npm install


Now you'll need a local postgres database to store Botlers state.

Create a database with the name room_service (see /config/config.js).

You'll also need to change the username in /config/config.js to one you have locally.

Now set up the database and migrations by running

npm run prestart

You will need to redo this anytime there is a database change.


You'll also need a local ngrok server running to reroute traffic from the internet to your local server.

Do this by running

ngrok http 3000

It should give you two ngrok urls. Copy the https one (e.g. into /config.json in the localBaseUrl field.

You can now build Botler itself using

npm run build

And run the server itself using

npm start

You should be able to confirm that your server is working by visiting localhost:3000/atlassian-connect.json or the ngrok address from /config.json.


You'll now be able to install your local addon into an actual Hipchat room by going to the room and clicking Integrations -> Install new integrations, then clicking the Install an integration from a descriptor URL link at the bottom of the page.

When the modal opens, enter your ngrok url (e.g and follow the prompts.