Create Slack App
First, you will need to navigate to Slack api to create an app with a name and a Slack domain. Here we walk through creating a simple slack app which allows a bot to post a message to a user.
We suggest setting up your Slack app on a development workspace first.
- Navigate to Slack’s Your Apps page and click Create an App.
- Enter an App Name, for example, ScriptRunner Integration.
- Choose your Development Slack Workspace. You’ll need to either sign in to your workspace or create a new workspace to add it as your development workspace.
- Navigate to OAuth & Permissions and click Add an OAuth Scope under Bot Token Scopes.
These scopes tell your app the permissions that it has access to, such as sending messages or viewing rooms.
For example, add the im:write scope if you want your Slack bot to post a message to a user. You can edit this later to add extra permissions, such as chat:write and chat:write:public to post to a channel.
- Once you have added at least one scope, navigate to App Home.
- Click Edit to change the Display Name and Default username for your bot (the app uses the bot user to post in the workspace). The Display Name is the name that will be displayed on Slack when a message is sent.
- Click Save.
- Navigate back to the OAuth and Permissions tab and click Install to Workspace to install the app.
The Bot Oauth Access Token now displays at the top of the OAuth & Permissions page. This is the token the feature needs to send messages, click the Copy button.
Set up the Slack Resource
Navigate to ScriptRunner→ Resources→ Add New Item→ Slack Connection.
Provide a name for the connection in Connection Name. For example, slack or if you use multiple workspaces use the workspace name.
Enter the Bot OAuth Token for your Slack workspace in Token.
For help getting your Bot OAuth Token see Create a Slack App above.
The token provided can be viewed by administrators.
Click Preview to validate the connection using the token provided.
Click Add. Your Slack connection is now configured.
To test the connection, navigate to the ScriptRunner→ Script Console.
Use the simple script below to test that the bot can post to a user and/or a channel.
We recommend you test your slack connection using your own user details, or set up a test slack room.
When sending a message to a Slack channel the scope chat:write is required… for a public channel chat:write_public is required. To send a direct message the scope users:read.email is required.
Accepted values for the channel argument (the second argument) are public or private channel name (or ID), or a user’s email address, or ID, to send a direct message.
The full list of allowed parameters that can be used to format your Slack messages can be found here.
chat:write: send messages to channels
chat:write.public: send messages to channels the bot user user isn’t a member of.
files:write: upload files
users:read and users:read.email: send direct messages to a user
chat:write.customize: send messages as bot user with a customized username and avatar
Having set up your Slack connection, you can now use it in your ScriptRunner scripts using the resource Connection Name.
Using Blocks and Attachments
Use the block kit builder to preview your messages.
Uploading a File
Upload file to a Slack channel. Scope files:write is required. You can either upload a file to a channel (if the bot user is part of this channel) or to a specific user:
To send an attachment the app must be added to the channel, which you can do by clicking the Add apps link from the channel details, then the More menu.
The full list of allowed parameters can be found here.