Hubot Discourse adapter

A Discourse adapter for Hubot.

A bot here will only be called in for topics it is notified for.

To get up and running, the adapter requires a few hubot variables to be set:

• HUBOT_DISCOURSE_USERNAME the username the bot will connect as.
• HUBOT_DISCOURSE_KEY the API key for the user. This needs to be a user API key, not a site-wide API key.
• HUBOT_DISCOURSE_SERVER the discourse server eg https://discourse.example.com/.

Getting started

npm install -g yo generator-hubot
mkdir my-awesome-hubot && cd my-awesome-hubot
yo hubot --adapter=discourse-adapter

Discourse configuration

By default, Discourse does not send users alert messages unless directly notified via @username, or by quoting.

In order to receive messages without a direct reply, you may either set the bot account's watched topics/categories to "watched" manually, or allow for "opt-in notifications".

For opt-in notifications, set the bot's user preferences, notifications and set When I post in a topic, set that topic to Watching After the first reply, Hubot will then listen for any post after its first reply.

Private Messages

Discourse adapter has a special mechanism to ensure a private reply to a post.

In a bot's config you can set the res.envelope.pm to ensure a reply goes through a PM to a user.

Set the res.envelope.pm to true. If the message is already a PM, the bot will reply as normal. If the message is public, the bot will create a new PM and send it to the user.

  robot.hear /private hello/i, (res) ->
    res.envelope.pm = true
    res.send "I will reply hello privately!"

Arbitrary room messaging

The Discourse adapter supports messaging rooms via res.robot.messageRoom. If given a comma separated list of strings, this will be a new PM. If the first argument is a topic id, this will create a new post in the specified topic.

  robot.hear /alert admins/i, (res) ->
    res.robot.messageRoom "admin1,admin2", "topic to give to two admins", "this is a post I want to give to admins"

  robot.hear /bump a post/i, (res) ->
    res.robot.messageRoom 123, "I am posting in another existing post"

Message info

After "hearing" something, the returned Response object (res) contains the raw message, with a few extensions.

res.message.text - the text of the message res.message.title - the topic title of the heard post res.message.slug - the URL of the heard post res.message.pm - a boolean to detect whether or not this message was sent as a PM. res.envelope.user.username - the username that sent the message to this bot.