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 eghttps://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.