Go to Slack

Developing approval workflows

Use cases:
  • Announcement gating
  • Editorial control
Works with:
  • Events API
  • Message Buttons
Code samples:

Allow people to post announcements to a restricted channel from time to time, with admin approval. This bot surfaces requests to the admin team for approval, and posts the announcements on behalf of the author once approved.

How it works

An announcement approval flow at work

1. Receive a direct message

To find out when a user sends a direct messages to the app's bot we need to subscribe to the im.message bot event sent out through the Events API. The Events API sends a POST request to a specified URL whenever certain events occur in a Slack workspace. In the case of the im.message bot event, Slack will send an event as soon as the app's bot receives a direct message. The event will include information about both the message and the user who sent it.

2. Open a dialog

Once a user sends the bot a direct message, the bot replies with a button to start a new announcement. When a user clicks this button, the bot will receive a request on its Interactive Components endpoint. Using the trigger_id in that payload, the bot can make a call to the dialog.open endpoint to open up a dialog with the user. The user can draft their announcement in this dialog and submit it to the bot. To include interactive functionality such as buttons and dialogs, you'll need to enable Interactive Components in the app settings and supply a URL.

3. Preview the message

When the bot receives the dialog submission, the bot will respond to the direct message with a preview of what that announcement would like using the chat.postMessage method. The app will also append a 'send request' message button to the message. The user can click this button to send a request to an admin for approval.

4. Send the message to an approver

When the user clicks the 'send request' button, the app will receive a POST request on its Interactive Message endpoint. The request will include details about who clicked the button, the contents of the original message, and a response URL. The response URL can be used by the app to update the content of the original message using an HTTP request with a JSON payload. When the message action request is received, the bot sends a direct message to a predefined approver asking them to either 'accept' or 'reject' the message using message buttons. At the same time, it sends an update to the user using the response URL to let them know that the message is pending approval.

5. Let the user make the final decision

Once the admin has approved the announcement, the app sends a message to the user using the chat.postMessage web API method. The message shows the updated status of the approval along with "post announcement" and "cancel" message buttons.

6. Post the message to the channel

When the user is ready to post the announcement, they can click the "post announcement" button, and the announcement will be posted to the announcements channel using chat.postMessage and the installers bearer token. The app can then replace its own "post announcement" message to the user with a confirmation that it's been posted, and optionally the link to the announcement itself.

To post into a restricted channel, this kind of app must either be installed by a team admin approver _or_ a user with posting permissions in that channel.

Customization suggestions

  • Allow for multiple approvers
  • Let the user select which restricted channel they want to post to
  • Let the user select from a pre-determined list of approvers
  • Post approval logs into a public channel

Other use cases

  • Allow internal communications teams to post on behalf of executives
  • Other approval workflows such as PTO, conference sponsorships, etc.

Diagram

A flow diagram from an effective approval workflow

Related documentation