Email This Issue
📈 Marketplace❓ Support❤️ Feedback🏠 META-INF Apps
Email This Issue - for Jira Server/Data Center
Email This Issue - for Jira Server/Data Center
  • ⬇️Start Here
  • Email This Issue - for Jira Server/DC
  • Features
  • Secure the email channel with Email This Issue
  • Comparing Email This Issue and Jira Server/DC
  • 🤓Documentation
    • Outgoing Emails
      • Sending manual emails
        • The difference between email editors
        • Enabling template categories so templates can be chosen on the Email screen
        • Mail Generation Queue (formerly called Event Queue)
        • Manual Email Default Settings
      • Sending issue filters by email
      • Email templates
        • Adding custom macro to email templates
        • Adding Email Audit Log to email templates
        • Adding fields to email templates
        • Adding issue comments to emails
        • Adding issue link information to your template
        • Adding issue operation links to the email
        • Adding a signature with a company logo to emails
        • Adding user properties to emails
        • Disabling links and avatars or icons in templates
        • Formatting Date and Time values
        • Using reply templates
        • Using Mail Body Initializer templates
        • Rendering templates within templates
        • Velocity Context in email templates
        • Formatting number values
        • Searching for issues in email templates
        • Changelog information in email templates
        • Canned responses
      • Contexts
        • Context Resolution Algorithm
      • Event Notifications
      • Distribution lists
      • Workflow post functions
      • Custom fields
    • Incoming Emails
      • Attachment Filtering
      • Next Generation Mail Handlers
        • Jira automation and Next Generation Mail Handlers
        • Using regular expressions
      • Classic Mail Handlers - Deprecated
        • Mail Handler Error Log
        • Step-by-step Classic Mail Handler to Next Generation Mail Handler migration aid
        • Field Rules
        • Phasing out the Classic Mail Handler
        • Comparing the Classic and the Next Generation Mail Handlers
    • Integrations
      • CRM for Jira
      • nFeed
      • Glass Documentation
      • API - Integration with other services
    • Administration
      • General configuration
      • Email Audit Log
      • Outgoing Mail Connections
      • Outgoing Mail Queue
      • Incoming Mail Connections
      • Incoming Mail Queue
      • Incoming Mail Log
      • Backup and restore settings
        • Backup and restore administration
          • Backup menu
          • Restore menu
        • Backup and Restore Tutorials
          • Backup and restore for empty email settings
          • Backup and restore only parts of a configuration
          • Backup and restore every setting in the same instance
      • OAuth2 Authorizations in Email This Issue
        • OAuth2 Client Credentials
        • Authorizing Email This Issue to access Gmail accounts
        • Authorizing Email This Issue to access Microsoft 365 accounts
        • Enabling OAuth2 Authorization in your Google Account
        • Enabling OAuth2 authorization in your Microsoft 365 account
        • Troubleshooting guides for Microsoft OAuth2 Connections
          • How to fix "Authorization Was Interrupted" error
          • How to fix "BAD User is authenticated but not connected" error
          • How to fix "401 Unauthorized" error
          • How to fix "key expires_in " error
          • How to fix "Need admin approval" error
      • Alerting via Webhooks
        • Webhooks
          • Configuring Slack to receive webhooks
          • Configuring OpsGenie to receive webhooks
        • Webhook execution logs
      • Email Security
    • Service management integration
    • JQL Functions
    • Top-level menu navigation
  • ☁️Server to Cloud Migration
    • Server to Cloud - Automatic Migration tool
    • Server to Cloud - Manual migration guide for Email This Issue
      • Overview of available features
      • Differences of the Server and Cloud user interface
      • Migrating Outgoing Settings
        • Migrating Templates
        • Migrating Notifications
        • Migrating Manual Email Defaults
        • Migrating Contexts
        • Migrating Canned Responses
        • Migrating Post Functions
        • Migrating Outgoing Mail Connections
      • Migrating Incoming Settings
        • Migrating Classic Mail Handlers
        • Migrating Next Generation Mail Handlers
        • Migrating Incoming Mail Connections
        • Migrating Incoming Mail Queue Settings
        • Migrating Incoming Mail Log Settings
      • Migrating Other Settings
        • Migrating OAuth2 Credentials
        • Migrating global default email settings
        • Migrating permissions for sending emails manually
        • Migrating recipient restrictions
  • ❓FAQ
    • FAQ
      • How to bypass workflow conditions
      • How to avoid email loops
      • How to control who to send emails to
      • How to customize Email From in outgoing emails
      • How to enable logging
      • How to install license keys
      • How to find out why the Email button is missing
      • How to obtain a community or non-profit license
      • How to prevent duplicate emails
      • How to remove old content from reply emails
      • How to send personalized emails to recipients
      • How to set up auto-reply or acknowledgment emails
      • How to track cases when you don't get any emails
      • How to view the log of incoming and outgoing emails
      • The iOS Mail app does not show attachments
      • How to route emails to projects
      • How to maintain email threads in Jira
      • How to fix issues with a corrupt index state
      • How to set polling interval for mail accounts manually
    • Tutorials
      • Configuring email approval
      • Customizing the email template used with manual emails
      • Enhance Jira Service Management with Email This Issue
      • Getting Started
      • Setting up an Email Help Desk
      • Setting up customized notifications
      • Setting up a Service Management with a Next-Gen Mail Handler
  • 🌪️Misc
    • Open Source Components
    • Pricing Updates
      • Pricing Update effective October 1st 2018
      • Pricing Update effective December 1, 2021
    • End of Support Policy
    • Security Advisories
      • Email This Issue Security Advisory 2020-02-18
    • Database Tables
    • Translations
  • 🆕Release Notes
    • Release notes
      • 9.x.x
        • 9.15.0 Jira 10 compatibility
        • 9.13.0 Improvements and Fixes
        • 9.11.0 Improvements and fixes
        • 9.10.0 Major improvements and fixes
        • 9.9.1 Improvements and fixes
        • 9.9.0.2 Major improvements and fixes
        • 9.8.0 Improvements and fixes
        • 9.7.0 Improvements and fixes
        • 9.6.0 Improvements and fixes
        • 9.5.0 Improvements and fixes
        • 9.4.0 Bugfixes
        • 9.3.3. Improvements and fixes
        • 9.3.2 Major improvements
        • 9.3.1 Automatic cloud migration
        • 9.2.2.1 Bugfixes
        • 9.2.2 Improvements and fixes
        • 9.2.1.3 Compatibility changes for Jira 9.0.0
        • 9.2.1 Major improvements
        • 9.2.0 Improvements and fixes
        • 9.1.1 Improvements and fixes
        • 9.1.0.1 Alerting and other major new features
        • 9.0.2 Bugfixes, next step in deprecating the Classic Mail Handler
        • 9.0.1 Minor improvement and fixes
        • 9.0.0 Major improvements
        • 9.12.0 Improvement and fixes
        • 9.17 Improvements and Fixes
        • 9.18.0 Improvements and fixes
      • 8.1.x
        • 8.1.3 Classic handler is deprecated, timezone support, bug fixes
        • 8.1.2 Important bug fixes
        • 8.1.1 Microsoft 365 OAuth2, improvements and fixes
        • 8.1.0 Microsoft 365 OAuth2, improvements and fixes
      • Up to 8.0.6
Powered by GitBook
On this page
  • General information
  • Manually creating and configuring a Slack app
  • Creating a Slack app to use with Email This Issue (required)
  • Preparing the Slack app to use with Email This Issue (required)
  • Calling the Web API
  • Permission scopes
  • Troubleshooting
  • Setting up messaging (optional)
  • Composing custom content
  • Headers
  • Message payload (JSON body)

Was this helpful?

  1. Documentation
  2. Administration
  3. Alerting via Webhooks
  4. Webhooks

Configuring Slack to receive webhooks

PreviousWebhooksNextConfiguring OpsGenie to receive webhooks

Last updated 3 years ago

Was this helpful?

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: .

  • As a result of an automated OAuth authorization flow ("OAuth dance"). For more information, see the Slack documentation: .

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:

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)

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.

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

7. Go to OAuth & Permissions under Features to add OAuth permission scopes:

8.Go to Install App under Settings to initiate the installation or the re-installation of the app, including the subsequent authorization flow.

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.

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:

Permission scopes

The required permission scopes are the following:

The optional permission scopes are the following:

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)

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

Compose custom content in the following ways:

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:

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:

curl -X POST -H 'Authorization: Bearer xoxb-AAAAAAAAAAAAA-BBBBBBBBBBBBB-CCCCCCCCCCCCCCCCCCCCCCCC' -H 'Content-type: application/json' \
--data '{"channel":"C01QZLFBK71","text":"This is a sample message from JETI."}' https://slack.com/api/chat.postMessage

1. As an organizational Slack administrator, visit the , then click on the Create New App button.

5. Obtain the bot user access token by copying it from the app configuration page:

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:

: to post messages into a channel (where the bot/user is member, has access to)

: to list info about public channels, as we shall explicitly provide the channel's ID (extracted from the response of call)

: to list info about private channels, as we shall explicitly provide the channel's ID (extracted from the response of call)

: 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:

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: .

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: .

Using blocks and, optionally, attachments For more information, see the Slack documentation: . Note: This is the recommended option.

Using predefined fields and, optionally, attachments. For more information, see the Slack documentation: .

🤓
https://api.slack.com/apps/%7Bapp-id%7D/general
https://api.slack.com/methods/oauth.v2.access
Enabling interactions with bots
Slack app management/config page
https://api.slack.com/apps/{app-id}/install-on-team
https://api.slack.com/methods/conversations.list
https://api.slack.com/web
https://api.slack.com/methods/chat.postMessage
https://api.slack.com/methods/chat.postMessage#arg_blocks
chat:write
channels:read
conversations.list
groups:read
conversations.list
chat:write.public
https://api.slack.com/scopes
https://api.slack.com/messaging
https://api.slack.com/messaging/composing
Block Kit Builder
Message Builder
https://api.slack.com/reference/surfaces/formatting
https://api.slack.com/messaging/composing/layouts