Slack Alert Integration Setup

Back to Alerts

Slack Alert Integration Setup Guide

This guide walks you through setting up Slack as an alert channel in JourneyGuard. You will create your own Slack App, install it into your workspace, and paste the bot token into JourneyGuard's alert form.

The whole process takes about 5 minutes and only needs to be done once per workspace.

Prerequisites

  • A Slack workspace where you have permission to install apps. If you are not a workspace admin, ask your admin to approve the install after you create it.
  • Access to a JourneyGuard account with permission to create/edit alerts.

1. Create a Slack App

  1. Go to https://api.slack.com/apps and sign in with the Slack workspace where you want alerts delivered.
  2. Click Create New App.
  3. Choose From scratch.
  4. Enter a name (for example, JourneyGuard Alerts) and pick the target workspace, then click Create App.

You will land on the app's Basic Information page.

2. Add the Required OAuth Scopes

JourneyGuard needs six Bot Token scopes. From the left sidebar of your Slack App page, open OAuth & Permissions, scroll down to Scopes → Bot Token Scopes, and click Add an OAuth Scope for each of the following. The list must match exactly:

Scope Why JourneyGuard needs it
chat:write Post alert messages into channels the bot is a member of.
chat:write.public Post into public channels the bot has not been invited to.
files:write Upload failure screenshots directly to Slack.
im:write Open direct-message conversations with users for DM alerts.
users:read Resolve Slack user IDs when sending DM alerts.
users:read.email Match Slack users by email address when needed.

Double-check the list before moving on. Missing scopes are the most common reason the "Test Slack" button fails later.

3. Install the App to Your Workspace

  1. Still on the OAuth & Permissions page, scroll to the top and click Install to Workspace (or Request to Install if your workspace requires admin approval).
  2. On the confirmation screen, review the requested scopes and click Allow.
  3. Slack will redirect you back to the OAuth & Permissions page and reveal a Bot User OAuth Token that starts with xoxb-.

4. Copy the xoxb- Bot Token

  1. Click Copy next to the Bot User OAuth Token. It looks like xoxb-1234567890-1234567890123-abcdefghijklmnopqrstuvwx.
  2. Treat this like a password. Anyone with the token can post messages as your bot.
  3. You will paste it into JourneyGuard in step 7. If you lose it, come back to this page and copy it again.

JourneyGuard stores the token encrypted at rest, so it never sits in plain text in the database.

5. Find the Channel ID

Slack channel IDs look like C0123ABCD (a C, G, or D prefix followed by uppercase letters and digits). To find the ID for the channel you want alerts posted to:

Desktop app or web:

  1. Open the target channel.
  2. Click the channel name at the top to open channel details.
  3. Scroll to the bottom of the About tab. The Channel ID is shown there with a copy button.

Alternative (right-click):

  1. Right-click the channel in the sidebar and choose Copy link.
  2. The link looks like https://your-workspace.slack.com/archives/C0123ABCD. The last path segment (C0123ABCD) is the channel ID.

Save the channel ID for step 7.

6. (Optional) Find User IDs for Direct Messages

If you also want the alert delivered as a DM to one or more Slack users, collect their user IDs. User IDs look like U0123ABCD.

  1. Open the user's Slack profile.
  2. Click the More button (three dots) in the profile panel.
  3. Choose Copy member ID.

Repeat for each user. You will paste them into JourneyGuard as a comma-separated list, for example: U0123ABCD, U0456DEFG.

Leave this field blank if you only want the alert to land in a channel.

7. Invite the Bot to the Target Channel

For private channels, and as a good default for public channels too, invite the bot so Slack accepts posts without relying on chat:write.public:

  1. Open the channel in Slack.
  2. Type /invite @YourAppName (replace YourAppName with the app name from step 1) and press Enter.

If you skip this step, the bot can still post into public channels because of the chat:write.public scope, but private channels will return not_in_channel until the bot is invited.

8. Paste the Values into JourneyGuard and Test

  1. In JourneyGuard, open Alerts and either create a new alert or edit an existing one.
  2. Set Alert Type to Slack. The form will swap Email/SMS fields for the Slack configuration fields.
  3. Fill in:
    • Slack Bot Token: the xoxb-... value from step 4.
    • Slack Channel ID: the channel ID from step 5 (e.g. C0123ABCD).
    • Slack DM User IDs: optional, comma-separated user IDs from step 6.
  4. Click Test Slack.
  5. You should see "Slack test message sent" in JourneyGuard and a test alert land in the channel (and any DM targets) within a few seconds.
  6. Click Save to persist the alert.

If the test fails, the error message from Slack is surfaced directly in the UI. The common cases are:

Slack error What to check
invalid_auth The bot token is wrong or was regenerated. Copy the token again from step 4.
channel_not_found The channel ID is wrong, or the workspace does not contain that channel.
not_in_channel Private channel and the bot has not been invited. Run /invite @YourAppName.
missing_scope One of the six scopes from step 2 is missing. Add it and reinstall the app.

Rotating or Revoking the Token

  • To rotate: on the OAuth & Permissions page click Regenerate Token, copy the new value, and paste it back into the JourneyGuard alert form.
  • To revoke: uninstall the app from Basic Information → Manage Distribution → Uninstall App. All alerts using that token will start failing with invalid_auth.

That's it. Once the token, channel ID, and (optional) DM user IDs are saved on an alert, JourneyGuard posts a Block Kit alert with the failing monitor's details and, for Journey/Visual monitors, uploads the failure screenshot directly to Slack.

Copyright © Ayalr.com 2024