mirror of
https://we.phorge.it/source/phorge.git
synced 2025-01-09 06:11:01 +01:00
445caf1d97
Summary: Using `##` can cause some formatting issues, see D13071. Test Plan: See D13071. Reviewers: epriestley, #blessed_reviewers, chad Reviewed By: epriestley, #blessed_reviewers Subscribers: Korvin, epriestley Differential Revision: https://secure.phabricator.com/D13072
89 lines
3.6 KiB
Text
89 lines
3.6 KiB
Text
@title Chat Bot Technical Documentation
|
|
@group 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.
|
|
|
|
NOTE: The chat bot is somewhat experimental and not very mature.
|
|
|
|
= 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:
|
|
|
|
- @{class: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.
|
|
- @{class:PhabricatorBotFeedNotificationHandler} This handler posts
|
|
notifications about changes to revisions to the channels listed in
|
|
`notification.channels`.
|
|
- @{class:PhabricatorBotLogHandler} This handler records chatlogs which can
|
|
be browsed in the Phabricator web interface.
|
|
- @{class:PhabricatorBotSymbolHandler} This handler posts responses to lookups
|
|
for symbols in Diffusion
|
|
- @{class: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
|
|
@{class:PhabricatorBotHandler}.
|
|
|
|
= Conduit =
|
|
|
|
Some handlers (e.g., @{class: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
|
|
@{article:Managing Daemons with phd} for more information.
|