> ## Documentation Index
> Fetch the complete documentation index at: https://docs.obsy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Slack

> Connect Slack for incident channels, notifications, and two-way message sync.

The Slack integration lets Obsy:

* Auto-create a dedicated channel for each incident
* Mirror Slack messages into the Obsy incident timeline
* DM you when a test message is sent or when you're assigned an incident role
* Post incident notifications to a general `#incidents` channel

## Connecting Slack

1. Go to **Integrations** in the sidebar.
2. Click **Connect Slack** in the Slack card.
3. You are redirected to Slack's OAuth page — authorize the Obsy app for your workspace.
4. You are redirected back to Obsy's Integrations page with a confirmation toast.

<Note>
  Only one Slack workspace can be connected per Obsy organization. If you need to switch workspaces, disconnect the current one and reconnect with the new workspace.
</Note>

## Required bot scopes

The Obsy Slack app requests these OAuth scopes:

| Scope              | Purpose                                       |
| ------------------ | --------------------------------------------- |
| `channels:manage`  | Create and archive public channels            |
| `channels:read`    | List channels the bot can see                 |
| `channels:join`    | Join public channels to post messages         |
| `chat:write`       | Post messages in channels and DMs             |
| `groups:read`      | List private channels the bot is a member of  |
| `groups:write`     | Create and manage private channels            |
| `im:read`          | Read direct message history                   |
| `im:write`         | Open DM conversations                         |
| `users:read`       | Look up users by ID                           |
| `users:read.email` | Look up users by email (for role assignments) |

## Sending a test message

1. Go to **Integrations → Slack card**.
2. Click **Send test message**.
3. Optionally pick a specific channel, or leave blank to receive a DM.
4. Click **Send**.

If the test fails, the error message explains why (e.g. "Bot is not in this channel" or "Missing scope"). The most common fix is to invite the bot to the channel: `/invite @obsy` in Slack.

## Two-way message sync

Messages you type in an incident's Slack channel are synced back into the Obsy incident timeline in real time.

**Setup required:**

1. In your Slack App settings (api.slack.com/apps), go to **Event Subscriptions**.
2. Enable events and set the **Request URL** to:
   ```
   https://api.obsy.ai/api/v1/webhooks/slack/events
   ```
3. Under **Subscribe to bot events**, add:
   * `message.channels` — for public channels
   * `message.groups` — for private channels
4. Save and reinstall the app if prompted.

**Verifying sync is working:**

* Type a message in the incident Slack channel.
* Open the incident in Obsy — the message should appear in the timeline within a few seconds.
* If no messages appear and you set up Events correctly, check that the Slack app was reinstalled after adding the event subscriptions.

## Disconnecting Slack

Go to **Integrations → Slack card** and click **Disconnect**. This removes the workspace connection and the stored bot token. Existing incident channels in Slack are not affected.

## Troubleshooting

<AccordionGroup>
  <Accordion title="'not_in_channel' error when posting to a channel">
    The bot needs to be a member of the channel. Run `/invite @obsy` in the target channel. For incident channels, Obsy joins automatically when creating the channel.
  </Accordion>

  <Accordion title="Test DM fails">
    Ensure your Obsy account email matches your Slack email. Obsy uses your email to look up your Slack user ID for DMs. If they differ, the lookup fails.
  </Accordion>

  <Accordion title="Incident messages not appearing in the Obsy timeline">
    Check that Event Subscriptions are enabled and the `message.channels` event is subscribed. The Slack app must be reinstalled after adding new event subscriptions for them to take effect.
  </Accordion>
</AccordionGroup>