slack-integrator/README.md

Express-based starter kit for creating Slack integrations

[![Build Status](https://travis-ci.org/mdb/node-slack-integrator.svg?branch=master)](https://travis-ci.org/mdb/node-slack-integrator)

# node-slack-integrator

A very simple Express-based server for creating Slack integrations.

`node-slack-integrator` runs an Express server with an `/integration` endpoint.

## How to use

1. Log into your Slack and configure a slash command integration that posts to `<your-integration-host.com>/integration` when a Slack user enters `/some command`.

2. Deploy a `node-slack-integrator` instance to `<your-integration-host.com>`. Your `node-slack-integrator` instance should be instantiated with a `payload` method & a `hookPath` property.

The `payload` method receives Slack's post request and generates the appropriate payload your integration should post in your Slack.

The `hookPath` property specifies the unique part of your Slack hook endpoint. This can be found in your Slack's admin.

## Example

```javascript
// slack_integration.js
var Integrator = require('slack-integrator');

new Integrator({
  // a 'payload' method to generate a Slack-formatted payload object
  // this method receives the request Slack issues to your integration
  // in response to a user's `/command`, as well as a callback called
  // with the Slack-formatted payload object
  payload: function(request, callback) {
    // this should return the payload object containing the
    // data you wish to display in Slack
    // see Slack documentation regarding its format

    // example:
    callback({
      username: 'my bot',
      text: 'some text',
      channel: request.body.channel_id,
      icon_emoji: ':ghost:'
    });
  },

  // optional; if set, this ensures against requests from un-authorized Slacks
  token: 'the token provided by your Slack instance',

  // https://hooks.slack.com/services/<YOUR_HOOK_PATH>
  hookPath: 'the path to your Slack instance's hook endpoint'
});
```

Running `node slack_integration.js` runs an Express app at port 3000. Port 3000 can be overridden via a `PORT` environment variable, or by a `port` declared on the options object passed to your integrator during instantiation.

The slack integration instance's `/integration` endpoint can be used to receive slash command-prompted POST requests from Slack.