outofcoffee/slack-gateway repository overview

⁠Slack Gateway: An HTTP gateway for posting to Slack

With a single HTTP request, you can post a message, creating the channel first if it doesn't exist and invite people and groups.

⁠What can it do?

Runs as a server, listening for an HTTP request. Upon receipt of a message, the gateway:

• creates the given Slack channel if it doesn't exist
• ensures a list of users (or user groups) are in the channel (if not - invites them)
• posts the message to the channel

This removes the complexity of orchestrating many Slack API calls behind a simple endpoint.

⁠Instructions

• As a Slack admin, create a Slack app, add the required scopes (see below) and install it to your workspace
• Set environment variables
• Run!

⁠Getting started

If you'd like to run Slack Gateway yourself as a Docker container, you can do the following:

docker run -d \
    --env SLACK_USER_TOKEN="CHANGEME" \
    --env SLACK_CHANNEL_MEMBERS="jsmith,mjones" \
    --publish 8080:8080 \
    outofcoffee/slack-gateway

⁠Example usage

⁠Using Slack format

Send a message to a channel:

curl http://localhost:8080/messages/raw \
    --header "Content-Type: application/json" \
    --data '{"channel":"general", text":"Hello World!"}'
    

Send a message with attachments:

curl http://localhost:8080/messages/raw \
    --header "Content-Type: application/json" \
    --data '{"channel":"general", text":"Hello World!","attachments":[{"text":"More info","color":"#33ee33"}]}'

⁠Using simple key-value format

If you don't want to compose the JSON yourself, you can use a simpler, but slightly more limited, key-value format instead.

Send a message to a channel:

curl http://localhost:8080/messages/text \
    --data 'channel=general' \
    --data 'text=Hello%20World!'

Send a message as an attachment:

curl http://localhost:8080/messages/text \
    --data 'channel=general' \
    --data 'text=Hello%20World!' \
    --data 'title=Attachment' \
    --data 'attachment=true' \
    --data 'color=00ff00'

The available options for the key-value format are:

⁠Additional message keys

When using the key-value format, any additional keys are appended to the text message. For example:

curl http://localhost:8080/messages/text \
    --data 'channel=general' \
    --data 'key_one=foo' \
    --data 'key_two=bar' \
    --data 'key_three=baz'

This will result in message text such as the following:

key one: *foo* | key two: *bar* | key three: *baz*

⁠Setting the channel type

You can specify the channel type as public or private. This will be used when creating channels, or posting messages.

Set the channel_type query parameter in the HTTP request, or use the DEFAULT_CREATE_CHANNEL_TYPE environment variable.

Valid values:

• private
• public

Example using the query parameter:

curl http://localhost:8080/messages/text \
   --data 'channel=some-private-channel' \
   --data 'text=Hello%20world' \
   --data 'channel_type=private'

⁠Creating a Slack app

As a Slack admin, create a Slack app: https://api.slack.com/apps/new⁠

Add a bot user in the 'Bot Users' section:

https://api.slack.com/apps/<your app ID>/bots

Add the required scopes in the 'OAuth & Permissions' section:

https://api.slack.com/apps/<your app ID>/oauth

The scopes are:

chat:write:bot
channels:read
channels:write
groups:read
groups:write
users:read
usergroups:read

Install your app to your workspace. This will generate two tokens.

Copy the 'OAuth Access Token' and set it as the SLACK_USER_TOKEN. It should look like this:

xoxp-123456789012-123456789012-123456789012-abcdef1234567890abcdef1234567890

Copy the 'Bot User OAuth Access Token' and set it as the SLACK_BOT_TOKEN. It should look like this:

xoxb-123456789012-123456789012-abcdef1234567890abcdef1234567890

Don't forget to invite your app to any existing private channels, using:

/invite @YourAppName

⁠Environment variables

Configure the bot using the following environment variables.

⁠Basic variables

• SLACK_BOT_TOKEN - required to post to channels not containing the user who created the user token
• SLACK_USER_TOKEN - must have the right permission scopes (see 'Creating a Slack app' in this document)
• SLACK_CHANNEL_MEMBERS - users to invite to channels e.g. "janesmith,bob" (comma separated; default empty)
• SLACK_CHANNEL_GROUPS - user groups to invite to channels e.g. "devteam" (comma separated; default empty)

⁠Advanced variables

• HTTP_BIND_PORT (default 8080)
• HTTP_BIND_HOST (default 0.0.0.0)
• SLACK_CACHE_SECONDS - period to cache Slack objects like users and user groups (default 300)
• DEFAULT_CREATE_CHANNEL_TYPE (default 'private') - the default channel type to create if none is specified in the request