# Slack Integration

## Overview

MailTrixy's Slack integration allows your team to receive notifications about new conversations, reply to customers directly from Slack, and use slash commands to manage your inbox without leaving your workspace. This is ideal for teams that already live in Slack and want to triage customer messages without switching to another dashboard.

## Slack App Creation

1. Go to api.slack.com/apps and click Create New App.
2. Choose From scratch.
3. Enter an app name (e.g., "MailTrixy") and select the workspace you want to install it in.
4. Click Create App.

After creation, you will be on the app's settings page. You need to configure several sections, described below.

## OAuth Setup

OAuth allows MailTrixy to act on behalf of your Slack workspace.

1. In your Slack app settings, go to OAuth & Permissions.
2. Under Redirect URLs, add: `https://yourdomain.com/api/integrations/slack/callback`
3. Under Bot Token Scopes, add the following permissions:
   - `chat:write` — Send messages as the bot
   - `channels:read` — View channel information
   - `channels:history` — Read messages in public channels
   - `commands` — Handle slash commands
   - `im:read` — View direct messages to the bot
   - `im:history` — Read direct message history
   - `im:write` — Send direct messages
   - `users:read` — View user information
4. Click Install to Workspace and authorize the app.
5. Copy the Bot User OAuth Token (starts with `xoxb-`).
6. In MailTrixy, go to Settings → Channels → Slack and paste the token.

You also need the Signing Secret (found under Basic Information → App Credentials). This is used to verify that incoming requests are genuinely from Slack.

## Event Subscriptions

Event subscriptions let Slack notify MailTrixy when messages are posted.

1. In your Slack app settings, go to Event Subscriptions and toggle it On.
2. Set the Request URL to: `https://yourdomain.com/api/webhooks/slack/events`
3. Slack will send a challenge request to verify the URL. MailTrixy handles this automatically.
4. Under Subscribe to bot events, add:
   - `message.channels` — Messages in public channels
   - `message.im` — Direct messages to the bot
   - `app_mention` — When someone @mentions the bot
5. Click Save Changes.

## Slash Commands

Slash commands let your team interact with MailTrixy from any Slack channel.

1. In your Slack app settings, go to Slash Commands.
2. Create the following commands:

Command | Request URL | Description
--- | --- | ---
`/mailtrixy-inbox` | `https://yourdomain.com/api/slack/commands/inbox` | Show unread conversation count and recent messages
`/mailtrixy-reply` | `https://yourdomain.com/api/slack/commands/reply` | Reply to a conversation by ID
`/mailtrixy-assign` | `https://yourdomain.com/api/slack/commands/assign` | Assign a conversation to a team member
`/mailtrixy-status` | `https://yourdomain.com/api/slack/commands/status` | View system status and AI usage stats

## Channel Messaging

MailTrixy can post notifications to a designated Slack channel when certain events occur:

- New conversation: A new email, WhatsApp message, or other channel message arrives. Gated by the "Forward new messages to Slack" toggle — see below.
- AI reply sent: The AI auto-sent a reply (useful for monitoring).
- Low confidence: An AI reply was generated with a confidence score below your threshold and needs human review.
- Angry sentiment: An incoming message was flagged as angry, signaling a potential escalation.
- System alerts: AI provider errors, spending limit warnings, or connectivity issues.

To configure the destination, go to Settings → Integrations → Slack card → Select Channel and pick (or create) the Slack channel where notifications should be posted.

Each notification includes an action button to View in MailTrixy, which links directly to the conversation in your dashboard.

## Forwarding Inbound Messages (opt-in)

Forwarding every new customer message to Slack is a powerful signal for teams that triage in Slack, but it's a noisy signal for teams that don't. It is OFF by default — an active Slack connection alone no longer mirrors inbound activity.

1. Go to Settings → Integrations → Slack card.
2. Tick the "Forward new messages to Slack" checkbox. The status message confirms "Slack forwarding enabled".
3. Every future inbound message (Email, WhatsApp, SMS, Telegram, Slack DM, Live Chat) posts a "New message received" card to your selected Slack channel with From / Channel / Subject / Priority.
4. Untick the box at any time to stop forwarding again.

The preference is stored per workspace inside the Slack integration's encrypted credentials as `forward_new_messages`. Other notifications (AI reply, low confidence, angry sentiment, system alerts, manual Test Notification) are not affected by this toggle.