[Summary view] [Print] [Text view]

   1  @title Chat Bot Technical Documentation
   2  @group bot
   3  
   4  Configuring and extending the chat bot.
   5  
   6  = Overview =
   7  
   8  Phabricator includes a simple chat bot daemon, which is primarily intended as
   9  an example of how you can write an external script that interfaces with
  10  Phabricator over Conduit and does some kind of useful work. If you use IRC or
  11  another supported chat protocol, you can also have the bot hang out in your
  12  channel.
  13  
  14  NOTE: The chat bot is somewhat experimental and not very mature.
  15  
  16  = Configuring the Bot =
  17  
  18  The bot reads a JSON configuration file. You can find an example in:
  19  
  20    resources/chatbot/example_config.json
  21  
  22  These are the configuration values it reads:
  23  
  24    - ##server## String, required, the server to connect to.
  25    - ##port## Int, optional, the port to connect to (defaults to 6667).
  26    - ##ssl## Bool, optional, whether to connect via SSL or not (defaults to
  27      false).
  28    - ##nick## String, nickname to use.
  29    - ##user## String, optional, username to use (defaults to ##nick##).
  30    - ##pass## String, optional, password for server.
  31    - ##nickpass## String, optional, password for NickServ.
  32    - ##join## Array, list of channels to join.
  33    - ##handlers## Array, list of handlers to run. These are like plugins for the
  34      bot.
  35    - ##conduit.uri##, ##conduit.user##, ##conduit.cert## Conduit configuration,
  36      see below.
  37    - ##notification.channels## Notification configuration, see below.
  38  
  39  = Handlers =
  40  
  41  You specify a list of "handlers", which are basically plugins or modules for
  42  the bot. These are the default handlers available:
  43  
  44    - @{class:PhabricatorBotObjectNameHandler} This handler looks for users
  45      mentioning Phabricator objects like "T123" and "D345" in chat, looks them
  46      up, and says their name with a link to the object. Requires conduit.
  47    - @{class:PhabricatorBotFeedNotificationHandler} This handler posts
  48      notifications about changes to revisions to the channels listed in
  49      ##notification.channels##.
  50    - @{class:PhabricatorBotLogHandler} This handler records chatlogs which can
  51      be browsed in the Phabricator web interface.
  52    - @{class:PhabricatorBotSymbolHandler} This handler posts responses to lookups
  53      for symbols in Diffusion
  54    - @{class:PhabricatorBotMacroHandler} This handler looks for users mentioning
  55      macros, if found will convert image to ASCII and output in chat. Configure
  56      with ##macro.size## and ##macro.aspect##
  57  
  58  You can also write your own handlers, by extending
  59  @{class:PhabricatorBotHandler}.
  60  
  61  = Conduit =
  62  
  63  Some handlers (e.g., @{class:PhabricatorBotObjectNameHandler}) need to read data
  64  from Phabricator over Conduit, Phabricator's HTTP API. You can use this method
  65  to allow other scripts or programs to access Phabricator's data from different
  66  servers and in different languages.
  67  
  68  To allow the bot to access Conduit, you need to create a user that it can login
  69  with. To do this, login to Phabricator as an administrator and go to
  70  `People -> Create New Account`. Create a new account and flag them as a
  71  "Bot/Script". Then in your configuration file, set these parameters:
  72  
  73    - ##conduit.uri## The URI for your Phabricator install, like
  74      ##http://phabricator.example.com/##
  75    - ##conduit.user## The username your bot should login to Phabricator with --
  76      whatever you selected above, like ##phabot##.
  77    - ##conduit.cert## The user's certificate, from the "Conduit Certificate" tab
  78      in the user's administrative view.
  79  
  80  Now the bot should be able to connect to Phabricator via Conduit.
  81  
  82  = Starting the Bot =
  83  
  84  The bot is a Phabricator daemon, so start it with ##phd##:
  85  
  86    ./bin/phd launch phabricatorbot <absolute_path_to_config_file>
  87  
  88  If you have issues you can try ##debug## instead of ##launch##, see
  89  @{article:Managing Daemons with phd} for more information.