Configuring Slack to receive alerts via webhooks
General information
In order to communicate with Slack, you need to create an app that resides in its associated (development) workspace. For more information, see the Manually creating and configuring a Slack app and the Creating and preparing a Slack app to use with Email This Issue sections below.
In this stage, the app is local, and is called a single-workspace app (for internal use only). You can make the app public and distribute it among several other workspaces if needed, then call the local (or distributed) Slack app JETI notification assistant.
Note: As opposed to single-workspace apps, distributed apps require to implement OAuth 2.0 authorization to generate access tokens for each workspace and user. The distribution process can be avoided if all workspace admins create a dedicated local app to use with the Email This Issue app. In this guide, we’ll follow this path.
For authentication and authorization, Slack employs app tokens (app keys), that are long-lived bearer tokens associated with registered apps. They are bound to a single workspace, where the app is installed. For each and every app installation in new workspaces, a different access token is generated for that particular workspace. Access tokens only expire if:
A workspace owner fully uninstalls the app
Users individually remove their configurations
The account of the user who initially authenticated the Slack app is deactivated
Apps do not require to obtain temporary access tokens with the help of a refresh token, but they can use their permanent app token until it is revoked. App tokens can be retrieved the following way:
Manually installing the app in a workspace through the Slack App Management UI that can be used for accessing the client ID and the client secret. For more information, see the Slack documentation: https://api.slack.com/apps/%7Bapp-id%7D/general.
As a result of an automated OAuth authorization flow ("OAuth dance"). For more information, see the Slack documentation: https://api.slack.com/methods/oauth.v2.access.
Slack defines different types of tokens and access modes. We need the bot token type, as the JETI notification assistant acts as a bot user. A bot is a kind of technical account; it does not act in the name of a real user, but has its own identity. In our case, the access token is called Bot User OAuth Token.
For more information, see the Slack documentation: Enabling interactions with bots
The desired functionality is to post messages to a particular Slack channel. There are two possible solutions for achieving that. Use one of the following:
Web API, a REST-like interface with lots of available methods.
Webhooks, a dedicated endpoint to communicate something specific. The alerting feature in Email This Issue for Jira is based on the more sophisticated Web API.
Manually creating and configuring a Slack app
Since no automated authorization flow has been implemented so far, company Jira/JETI/Slack admins need to prepare Slack in order to integrate it manually with Email This Issue for Jira. In this case, a pre-configured, local Slack app can be linked to the Email This Issue for Jira app by providing some important authorization and configuration data on the alerting configuration page.
Creating a Slack app to use with Email This Issue (required)
1. As an organizational Slack administrator, visit the Slack app management/config page, then click on the Create New App button.
2. Pick an appropriate name for the app (for example “JETI notification assistant”) and select the workspace of your organization.
3. Create a bot user (the respective access token) for your app with appropriate permission scopes, configured for Web API usage.
4. Install the app into the associated workspace, then complete authorization.
5. Obtain the bot user access token by copying it from the app configuration page: https://api.slack.com/apps/{app-id}/install-on-team
6. Use the credentials from step 4 to configure a Slack connection in JETI. If you are not the Jira / Email This Issue admin of your organization, then consult with them. Provide both the access token and the target channel name
Preparing the Slack app to use with Email This Issue (required)
When the working Slack app is in place, do the following:
1. Add the app to the target channel through invitation or by mentioning the app in the conversation in the given private or public channel.
2. Normally, only the channel name is displayed on the Slack UI, regardless whether it is a native app or a web client. As an administrator, provide the channel ID in the place of the channel name on the webhook configuration form.
Note: A channel name can be changed, while the channel ID is constant in time (invariant). Renaming the channel in the background won’t affect the operation of previously configured webhooks.
3. To easily retrieve the channel ID, open the web UI of the selected Slack workspace in a browser, click the channel and read out the channel ID from the URL.
4. (Optional) The Slack web API can be used for retrieving the channel ID, for example by executing the request using cURL. For more information, see the Slack documentation: https://api.slack.com/methods/conversations.list
Calling the Web API
There is a dedicated method called chat.postMessage in the Web API to post messages into a channel (previously referred to as the Service URL). The body part is to be sent as an attachments argument or a blocks argument (JSON array).
For more information, see the Slack documentation:
https://api.slack.com/methods/chat.postMessage
https://api.slack.com/methods/chat.postMessage#arg_blocks
Permission scopes
The required permission scopes are the following:
chat:write: to post messages into a channel (where the bot/user is member, has access to)
channels:read: to list info about public channels, as we shall explicitly provide the channel's ID (extracted from the response of conversations.list call)
groups:read: to list info about private channels, as we shall explicitly provide the channel's ID (extracted from the response of conversations.list call)
The optional permission scopes are the following:
chat:write.public: This should only be added if the app have access to post messages to public channels without explicitly inviting it to the channel beforehand. Optionally, you can add the app to the workspace in general.
For more information, see the Slack documentation: https://api.slack.com/scopes
Troubleshooting
Typical authorization-related errors due to incorrect permissions or missing prerequisites are the following:
not_in_channel: If the app was neither added to the target channel beforehand, nor was the chat:write.public scope granted (if the target channel is a public channel).channel_not_found: If a private channel is the target channel and the app was not previously added to it as a member.
Important: If a permission scope was granted once, the administrator cannot revoke such a broader scope with simple re-installation of the app with more restricted scopes. To achieve this, the full app access shall be revoked and re-granted.
Setting up messaging (optional)
If you are about to define a full, custom message template on your own instead of relying on the built-in one, before you begin, see the Slack documentation on Messaging: https://api.slack.com/messaging.
Important: Messages are sent as a JSON body, so the Content-type header must be set to application/json, and the Authorization header has to be set, too.
Composing custom content
How the message payload is constructed, depends on the chosen formatting and how you want to modify the content or the appearance of the posted message. There are different levels of formatting and associated techniques to construct simple or more richer messages. For more information, see the Slack documentation: https://api.slack.com/messaging/composing.
Compose custom content in the following ways:
Using blocks and, optionally, attachments For more information, see the Slack documentation: Block Kit Builder. Note: This is the recommended option.
Using predefined fields and, optionally, attachments. For more information, see the Slack documentation: Message Builder.
Headers
Content-type: application/json (automatically added)
HTTP Authorization header {Bot-User-OAuth-Token}
Message payload (JSON body)
Character limitations are the following:
Text fields: a maximum of 4000 characters
Full messages: a maximum of 40000 characters (in blocks: 2000 characters)
For more information on basic formatting rules and rich message layouts, see the Slack documentation:
https://api.slack.com/reference/surfaces/formatting
https://api.slack.com/messaging/composing/layouts
For long sections, or less important details in the message, the auto expand/collapse function can be used. There is an auto expand/collapse mode in Slack, but applies only to one specific type of content: text attachments. It does not apply to any kind of block elements. The Rule activation condition is 700+ characters or 5+ lines of text.
Without using the half deprecated attachments, the only way to hide long parts of a message is by defining a button with an absolute link or using file attachments.
For example:
Last updated
