No description, website, or topics provided.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
examples
lib
test
.gitignore
.travis.yml
LICENSE.md
README.md
index.js
package.json

README.md

Build Status

The beepboop bot multi-team management node module

beepboop allows bot developers to run on the Beep Boop HQ bot hosting platform and support multiple teams from a single bot process. Simply require beepboop in your bot project and listen for events indicating a user has requested your bot to be added, updated, or removed from their team.

If you are using Botkit, we recommend using beepboop-botkit so spawning and connecting to teams is handled for you.

Install

npm install --save beepboop

Use

Testing your bot locally

TODO: Add link to multi-team article

At a minimum, the client needs the following environment variables set which can be obtained from the development area of the http://beepboophq.com site.

  • BEEPBOOP_RESOURCER -- url to the Beep Boop Server
  • BEEPBOOP_TOKEN -- authentication toke for Beep Boop Server
  • BEEPBOOP_ID -- unique identifier for your bot process

In production, these values will be set automatically.

Connect to Beep Boop and listen for events like so:

var BeepBoop = require('beepboop')

var beepboop = BeepBoop.start()

// listen for events
beepboop
  .on('open', function () {
    console.log('connected to resource server')
  })
  .on('add_resource', function (msg) {
    console.log('received request to add bot to team')
    // handle adding team to bot
  })

see examples/simple.js for more.

Module: beepboop

Module has exported function start

BeepBoop.start([options Object])

  • options.debug Boolean - Logs debug output if true
  • Returns an EventEmitter2 instance that emits the following events. The events emitted are largely pass-throughs of events emitted by the ws WebSocket implementation module used:

Event: open

  • Emitted when the connection is established.
beepboop.on('open', function () {
  console.log('connection to Beep Boop server opened')
})

Event: error

  • Errors with the connection and underlying WebSocket are emitted here.
beepboop.on('error', function (error) {
  console.log('Error from Beep Boop connection: ', err)
})

Event: close

  • Is emitted when the WebSocket connection is closed.
beepboop.on('close', function (code, message) {
  console.log('Connection to Beep Boop was closed')
})

Event: add_resource

Is emitted when an add_resource message is received, indicating a user has requested an instance of the bot to be added to their team.

beepboop.on('add_resource', function (message) {
  console.log('Team added: ', message)
  // Create a connection to the Slack RTM on behalf of the team
})

An add_resource message looks as follows:

{
  "type": "add_resource",
  "date": "2016-03-18T20:58:52.907804207Z",
  "msgID": "106e930b-1c83-4406-801d-caf04e30da71",
  // unique identifier for this team connection
  "resourceID": "75f9c7334807421bb914c1cff8d4486c",
  "resourceType": "SlackApp",
  "resource": {
    // Token you should use to connect to the Slack RTM API
    "SlackBotAccessToken": "xoxb-xxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx",
    "SlackBotUserID": "XXXXXXXXX",
    "SlackBotUserName": "name-of-bot-user",
    // Regular access token - will contain additional scopes requested
    "SlackAccessToken": "XXXXXXXXX",
    "SlackIncomingWebhookConfigURL": "https://<slack-team-name>.slack.com/services/XXXXXXXXX",
    "SlackIncomingWebhookChannel": "#channel-name",
    "SlackIncomingWebhookConfigURL": "https://hooks.slack.com/services/XXXXXXXXX/XXXXXXXXX/XXXXXXXXX",
    "SlackTeamName": "Name of Team",
    "SlackTeamID": "XXXXXXXXX",
    "SlackUserID": "XXXXXXXXX",
    "CUSTOM_CONFIG": "Value for CUSTOM_CONFIG"
  }
}

For keeping track of multiple team's RTM socket connections, you would want to create an mapping based on the message.resourceID, as it is the unique value you'll receive when a user requests to remove the bot from their team.

Event: update_resource

  • Is emitted when an update_resource message is received, indicating a request to update the instance of the bot has been sent. The bot maker updating the bot, or a bot owner updating configuration are two cases that can trigger an update.
beepboop.on('update_resource', function (message) {
  console.log('Team Updated: ', message)
  // may need to update local config for team or re-establish the Slack RTM connection
})

An update_resource message looks as follows, very similar to the add_resource:

{
  "type": "update_resource",
  "date": "2016-03-18T21:02:49.719711877Z",
  "msgID": "2ca94d34-ef04-4167-8363-c778d129b8f1",
  "resourceID": "75f9c7334807421bb914c1cff8d4486c",
  "resource": {
    // Token you should use to connect to the Slack RTM API
    "SlackBotAccessToken": "xoxb-xxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx",
    "SlackBotUserID": "XXXXXXXXX",
    "SlackBotUserName": "name-of-bot-user",
    // Regular access token - will contain additional scopes requested
    "SlackAccessToken": "XXXXXXXXX",
    "SlackTeamName": "Name of Team",
    "SlackTeamID": "XXXXXXXXX",
    "SlackUserID": "XXXXXXXXX",
    "CUSTOM_CONFIG": "Updated Value for Config"
  }
}

Event: remove_resource

  • Is emitted when an remove_resource message is received, indicating a bot owner has removed a bot from their team. You should disconnect from the Slack RTM API on behalf of the requested team.
beepboop.on('remove_resource', function (message) {
  console.log('Team Removed: ', message)
  // You'll want to disconnect from the Slack RTM connection you made, and perform any cleanup needed
})

A remove_resource message looks as follows:

{
  "type": "remove_resource",
  "date": "2016-03-18T20:58:46.567341241Z",
  "msgID": "a54f4b29-9872-45be-83fc-70ebc6ae7159",
  "resourceID": "75f9c7334807421bb914c1cff8d4486c"
}