Chat Bot Technical Documentation

Phabricator Technical Documentation (bot)

Configuring and extending the chat bot.

Overview

Phabricator includes a simple chat bot daemon, which is primarily intended as an example of how you can write an external script that interfaces with Phabricator over Conduit and does some kind of useful work. If you use IRC or another supported chat protocol, you can also have the bot hang out in your channel.

Configuring the Bot

The bot reads a JSON configuration file. You can find an example in:

resources/chatbot/example_config.json

These are the configuration values it reads:

• server String, required, the server to connect to.
• port Int, optional, the port to connect to (defaults to 6667).
• ssl Bool, optional, whether to connect via SSL or not (defaults to false).
• nick String, nickname to use.
• user String, optional, username to use (defaults to nick).
• pass String, optional, password for server.
• nickpass String, optional, password for NickServ.
• join Array, list of channels to join.
• handlers Array, list of handlers to run. These are like plugins for the bot.
• conduit.uri, conduit.user, conduit.cert Conduit configuration, see below.
• notification.channels Notification configuration, see below.

Handlers

You specify a list of "handlers", which are basically plugins or modules for the bot. These are the default handlers available:

• PhabricatorBotObjectNameHandler This handler looks for users mentioning Phabricator objects like "T123" and "D345" in chat, looks them up, and says their name with a link to the object. Requires conduit.
• PhabricatorBotFeedNotificationHandler This handler posts notifications about changes to revisions to the channels listed in notification.channels.
• PhabricatorBotLogHandler This handler records chatlogs which can be browsed in the Phabricator web interface.
• PhabricatorBotSymbolHandler This handler posts responses to lookups for symbols in Diffusion
• PhabricatorBotMacroHandler This handler looks for users mentioning macros, if found will convert image to ASCII and output in chat. Configure with macro.size and macro.aspect

You can also write your own handlers, by extending PhabricatorBotHandler.

Conduit

Some handlers (e.g., PhabricatorBotObjectNameHandler) need to read data from Phabricator over Conduit, Phabricator's HTTP API. You can use this method to allow other scripts or programs to access Phabricator's data from different servers and in different languages.

To allow the bot to access Conduit, you need to create a user that it can login with. To do this, login to Phabricator as an administrator and go to People -> Create New Account. Create a new account and flag them as a "Bot/Script". Then in your configuration file, set these parameters:

• conduit.uri The URI for your Phabricator install, like http://phabricator.example.com/
• conduit.user The username your bot should login to Phabricator with -- whatever you selected above, like phabot.
• conduit.cert The user's certificate, from the "Conduit Certificate" tab in the user's administrative view.

Now the bot should be able to connect to Phabricator via Conduit.

Starting the Bot

The bot is a Phabricator daemon, so start it with phd:

./bin/phd launch phabricatorbot <absolute_path_to_config_file>

If you have issues you can try debug instead of launch, see Managing Daemons with phd for more information.