With a single HTTP request, you can post a message, creating the channel first if it doesn't exist and invite people and groups.
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.
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"}]}'
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!'
- As a Slack admin, create a Slack app, add the required scopes (see below) and install it to your workspace
- Set environment variables
- Run!
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
Note: See the Environment variables section for the available configuration settings.
You can send messages to Slack Gateway using either the Slack format, or a simpler key-value 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"}]}'
For more information on the Slack post message format, see https://api.slack.com/
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 example above will send the text message as an attachment, with a particular colour and title.
The available options for the key-value format are:
Key | Required | Type | Purpose |
---|---|---|---|
channel | Yes | String | Channel name |
text | Yes, unless additional message keys used | String | Literal message text |
attachment | No | Boolean | Whether to send in attachment mode |
title | No | String | Attachment title |
color | No | String | Attachment color |
author_name | No | String | Attachment author name |
title_link | No | String | Attachment title link URL |
footer | No | String | Attachment footer text |
footer_icon | No | String | Attachment footer icon URL |
Additional message keys | No, unless text is empty |
String | See below |
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*
Note that underscores in key names are replaced with spaces, and the values are emboldened.
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'
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
Don't forget to save changes after adding scopes.
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
Slack doesn't permit apps to post to channels unless they have permissions.
If instead you wish to build and run locally, you can run:
./gradlew installDist
docker-compose build
Once built, set the environment variables in docker-compose.yml
. See the Environment variables section.
Then run with:
docker-compose up
If you change anything, don't forget to rebuild before running again.
Configure the bot using the following environment 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)
- 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
- Pull requests are welcome.
- PRs should target the
develop
branch. - Please run
ktlint
against the code first ;-)
Pete Cornish ([email protected])