Scripting | HUBOT
Scripting Hubot out of the box doesn’t do too much but it is an extensible, scriptable robot friend. There are hundreds of scripts written and maintained by the community and it’s easy to write your own. You can create a custom script in hubot’s scripts directory or create a script package for sharing with the community! Anatomy of a script When you created your hubot, the generator also created a scripts directory.
If you peek around there, you will see some examples of scripts. For a script to be a script, it needs to: live in a directory on the hubot script load path ( src/scripts and scripts by default) be a .coffee or .js file export a function By export a function, we just mean: module . exports = ( robot ) -> # your code here The robot parameter is an instance of your robot friend. At this point, we can start scripting up some awesomeness.
Hearing and responding Since this is a chat bot, the most common interactions are based on messages. Hubot can hear messages said in a room or respond to messages directly addressed at it. Both methods take a regular expression and a callback function as parameters. For example: module . exports = ( robot ) -> robot . hear /badger/i , ( res ) -> # your code here robot . respond /open the pod bay doors/i , ( res ) -> # your code here The robot.hear /badger/ callback is called anytime a message’s text matches.
For example: Stop badgering the witness badger me what exactly is a badger anyways The robot.respond /open the pod bay doors/i callback is only called for messages that are immediately preceded by the robot’s name or alias. If the robot’s name is HAL and alias is /, then this callback would be triggered for: hal open the pod bay doors HAL: open the pod bay doors @HAL open the pod bay doors /open the pod bay doors It wouldn’t be called for: HAL: please open the pod bay doors because its respond is bound to the text immediately following the robot name has anyone ever mentioned how lovely you are when you open the pod bay doors? because it lacks the robot’s name Send & reply The res parameter is an instance of Response (historically, this parameter was msg and you may see other scripts use it this way).
With it, you can send a message back to the room the res came from, emote a message to a room (If the given adapter supports it), or reply to the person that sent the message. For example: module . exports = ( robot ) -> robot . hear /badger/i , ( res ) -> res . send "Badgers? BADGERS? WE DON'T NEED NO STINKIN BADGERS" robot . respond /open the pod bay doors/i , ( res ) -> res . reply "I'm afraid I can't let you do that." robot . hear /I like pie/i , ( res ) -> res . emote "makes a freshly baked pie" The robot.hear /badgers/ callback sends a message exactly as specified regardless of who said it, “Badgers?
BADGERS? WE DON’T NEED NO STINKIN BADGERS”. If a user Dave says “HAL: open the pod bay doors”, robot.respond /open the pod bay doors/i callback sends a message “Dave: I’m afraid I can’t let you do that.” Messages to a room or user Messages can be sent to a specified room or user using the messageRoom function. module . exports = ( robot ) -> robot . hear /green eggs/i , ( res ) -> room = "mytestroom" robot . messageRoom room , "I do not like green eggs and ham.
I do not like them sam-I-am." User name can be explicitely specified if desired ( for a cc to an admin/manager), or using the response object a private message can be sent to the original sender. robot . respond /I don't like Sam-I-am/i , ( res ) -> room = 'joemanager' robot . messageRoom room , "Someone does not like Dr. Seus" res . reply "That Sam-I-am \n That Sam-I-am \n I do not like \n that Sam-I-am" robot . hear /Sam-I-am/i , ( res ) -> room = res . envelope . user . name robot . messageRoom room , "That Sam-I-am \n That Sam-I-am \n I do not like \n that Sam-I-am" Capturing data So far, our scripts have had static responses, which while amusing, are boring functionality-wise. res.match has the result of match ing the incoming message against the regular expression.
This is just a JavaScript thing , which ends up being an array with index 0 being the full text matching the expression. If you include capture groups, those will be populated res.match . For example, if we update a script like: robot . respond /open the (.*) doors/i , ( res ) -> # your code here If Dave says “HAL: open the pod bay doors”, then res.match[0] is “open the pod bay doors”, and res.match[1] is just “pod bay”.
Now we can start doing more dynamic things: robot . respond /open the (.*) doors/i , ( res ) -> doorType = res . match [ 1 ] if doorType is "pod bay" res . reply "I'm afraid I can't let you do that." else res . reply "Opening #{ doorType } doors" Making HTTP calls Hubot can make HTTP calls on your behalf to integrate & consume third party APIs. This can be through an instance of node-scoped-http-client available at robot.http .
The simplest case looks like: robot . http ( "https://midnight-train" ) . get () ( err , res , body ) -> # your code here A post looks like: data = JSON . stringify ({ foo : 'bar' }) robot . http ( "https://midnight-train" ) . header ( 'Content-Type' , 'application/json' ) . post ( data ) ( err , res , body ) -> # your code here err is an error encountered on the way, if one was encountered. You’ll generally want to check for this and handle accordingly: robot . http ( "https://midnight-train" ) . get () ( err , res , body ) -> if err res . send "Encountered an error :( #{ err } " return # your code here, knowing it was successful res is an instance of node’s http.ServerResponse .
Most of the methods don’t matter as much when using node-scoped-http-client, but of interest are statusCode and getHeader . Use statusCode to check for the HTTP status code, where usually non-200 means something bad happened. Use getHeader for peeking at the header, for example to check for rate limiting: robot . http ( "https://midnight-train" ) . get () ( err , res , body ) -> # pretend there's error checking code here if res . statusCode isnt 200 res . send "Request didn't come back HTTP 200 :(" return rateLimitRemaining = parseInt res . getHeader ( 'X-RateLimit-Limit' ) if res . getHeader ( 'X-RateLimit-Limit' ) if rateLimitRemaining and rateLimitRemaining < 1 res . send "Rate Limit hit, stop believing for awhile" # rest of your code body is the response’s body as a string, the thing you probably care about the most: robot . http ( "https://midnight-train" ) . get () ( err , res , body ) -> # error checking code here res . send "Got back #{ body } " JSON If you are talking to APIs, the easiest way is going to be JSON because it doesn’t require any extra dependencies.
When making the robot.http call, you should usually set the Accept header to give the API a clue that’s what you are expecting back. Once you get the body back, you can parse it with JSON.parse : robot . http ( "https://midnight-train" ) . header ( 'Accept' , 'application/json' ) . get () ( err , res , body ) -> # error checking code here data = JSON . parse body res . send " #{ data . passenger } taking midnight train going #{ data . destination } " It’s possible to get non-JSON back, like if the API hit an error and it tries to render a normal HTML error instead of JSON.
To be on the safe side, you should check the Content-Type , and catch any errors while parsing. robot . http ( "https://midnight-train" ) . header ( 'Accept' , 'application/json' ) . get () ( err , res , body ) -> # err & response status checking code here if response . getHeader ( 'Content-Type' ) isnt 'application/json' res . send "Didn't get back JSON :(" return data = null try data = JSON . parse body catch error res . send "Ran into an error parsing JSON :(" return # your code here XML XML APIs are harder because there’s not a bundled XML parsing library.
It’s beyond the scope of this documentation to go into detail, but here are a few libraries to check out:
The rest of this page is on the live site.