hubot-esa

A Hubot script handling webhooks and retrieving info from esa: https://esa.io

• Handle received webhooks
  • Post created
  • Post update
  • Post archived
  • Comment created
  • Member joined
• Retrieve info when someone talking about URL of esa
  • Post
  • Comment
• Retrieve stats of your team by hubot esa stats

Installation

Add to your Hubot project

$ npm install hubot-esa --save

Then add hubot-esa to your external-scripts.json.

Also you need some variables to environment your Hubot runs. See below.

Base Settings

export HUBOT_ESA_ACCESS_TOKEN='access_token'    # Required, your personal access token
export HUBOT_ESA_TEAM_NAME='gingypurrs'         # Required, your team name
export HUBOT_ESA_WEBHOOK_DEFAULT_ROOM='random'  # Required, room name you get notification by webhook
export HUBOT_ESA_WEBHOOK_ENDPOINT='/ginger/esa' # Optional, Default: "/hubot/esa"
export HUBOT_ESA_WEBHOOK_SECRET_TOKEN='stoken'  # Optional

HUBOT_ESA_ACCESS_TOKEN Required

• Generate and set your "Personal access token" from https://[your-team].esa.io/user/applications.

HUBOT_ESA_TEAM_NAME Required

• Set your team name

HUBOT_ESA_WEBHOOK_DEFAULT_ROOM Required

• Set channel/room.for webhook notification from esa as default e.g. general

HUBOT_ESA_WEBHOOK_ENDPOINT Optional (Default: /hubot/esa)

• Set the path for endopoint receives webhook from esa.
• Configure your completed uri at https://[your-team].esa.io/team/webhooks for Generic webhook

HUBOT_ESA_WEBHOOK_SECRET_TOKEN Optional

• If some text is set, hubot-esa verifies signature of HTTPS request by esa.io
• Same to secret you configured in https://[your-team].esa.io/team/webhooks for Generic webhook

HUBOT_ESA_JUST_EMIT Optional (Default: false)

• If true is set, disables messaging
• hubot-esa always triggers below custom events. so you can make customized behavior when receive webhooks

HUBOT_ESA_SLACK_DECORATOR Optional (Default: false)

• If true is set, decorates message for Slack

HUBOT_ESA_DEBUG Optional (Default: false)

• If true, then log receiving/emitting events

Use Built-in Slack Decorator

If you're using Hubot for Slack with hubot-slack, you can use built-in Slack decorator implemented for slack.attachment event.

Set env values like below.

export HUBOT_ESA_WEBHOOK_JUST_EMIT='true'       # Optional, Default: "false"
export HUBOT_ESA_SLACK_DECORATOR='true'         # Optional, Default: "false"

Enable Channel Selector for Slack

Select notified channel(room) dynamically by title of post on esa.

export HUBOT_ESA_SLACK_ROOM_SELECTOR='true'     # Optional, Default: "false"

If title includes tags like #dev #programming and channel which corresponds with that tag exist, notifications will be posted to each channels.

When not exist, try to find deepest directory name which corresponds with channel.

e.g. There are 3 channels in Slack: #dev, #programming, web (private)

Title of post on esa	Notified Channel
awesome article	default room
awesome article #dev #programming	#dev #programming
awesome article #dev #programming #ruby #web	#dev #programming web
dev/awesome article	#dev
dev/programming/awesome article	#programming

hubot must exist in each channels which is be notified.

Handle event listener manually

You can implement your script handles above events. For example your can build original message on your own :)

By below setting, disable posting by hubot-esa. Then you can get just emitted event.

export HUBOT_ESA_WEBHOOK_JUST_EMIT='true'       # Optional, Default: "false"

esa.hear.stats

• Trigger by someone says to hubot hubot esa stats
• With stats object: https://docs.esa.io/posts/102#5-1-0 and hubot Response object

robot.on 'esa.hear.stats', (res, stats) ->
  console.log(stats)

esa.hear.post

• Trigger by someone chats post url
• With post object: https://docs.esa.io/posts/102#7-2-0 and hubot Response object

robot.on 'esa.hear.post', (res, post) ->
  console.log(post)

esa.hear.comment

• Trigger by someone chats comment url
• With comment object: https://docs.esa.io/posts/102#8-2-0, post object: https://docs.esa.io/posts/102#7-2-0 and hubot Response object

robot.on 'esa.hear.comment', (res, comment, post) ->
  console.log(comment)
  console.log(post)

esa.webhook

• Trigger by receiving webhook
• With kind https://docs.esa.io/posts/37 and data object

robot.on 'esa.webhook', (kind, data) ->
  console.log(comment)

data:
  team: 'team name'
  user: 'user object by webhook'
  post: 'post object by webhook'
  comment: 'comment object by webhook'

Author

• @hmsk who is an esa lover (\( ⁰⊖⁰)/)

License

• MIT License