slack-gateway.md
1 --- 2 title: Slack Gateway 3 sidebar_position: 2 4 --- 5 6 import NetworkAccessRequiredSingleFeature from '@site/docs/partials/network-access-required.mdx'; 7 8 # Slack Gateway 9 10 Slack gateways integrate Agent Mesh with Slack workspaces, enabling users to interact with agents through Slack channels and direct messages. The gateway uses Socket Mode for real-time message processing without requiring public endpoints. 11 12 ## Overview 13 14 Slack gateways connect to Slack workspaces using the Slack Events API and Socket Mode. When users send messages in configured channels or direct messages to the bot, the gateway receives these events and forwards them to Agent Mesh as stimuli. Agent responses are sent back to Slack as reply messages. 15 16 Socket Mode establishes a WebSocket connection from the gateway to Slack's servers, eliminating the need for public-facing endpoints or webhook URLs. 17 18 <NetworkAccessRequiredSingleFeature /> 19 20 ## Prerequisites 21 22 Before creating a Slack gateway, verify that you have the following: 23 24 ### Slack App Configuration 25 26 You need a Slack App created in your workspace with the following: 27 28 1. Bot Token Scopes: The app must have appropriate OAuth scopes for messaging. 29 2. Socket Mode: Socket Mode must be enabled for the app. 30 3. Event Subscriptions: The app must subscribe to message events. 31 32 ### Required Slack Tokens 33 34 You need two tokens from your Slack App configuration: 35 36 | Token Type | Prefix | Purpose | 37 |------------|--------|---------| 38 | Bot Token | `xoxb-` | Authenticates API calls to send messages | 39 | App Token | `xapp-` | Establishes Socket Mode WebSocket connection | 40 41 ### Slack App Setup Steps 42 43 If you have not created a Slack App yet, follow these steps: 44 45 1. Go to [api.slack.com/apps](https://api.slack.com/apps) and click "Create New App" 46 2. Choose "From scratch" and provide an app name and workspace 47 3. Navigate to Socket Mode and enable it. Create an app-level token with `connections:write` scope. Save this token (starts with `xapp-`). 48 4. Navigate to OAuth & Permissions and add the following Bot Token Scopes: 49 - `app_mentions:read`—Receive mention events 50 - `channels:history`—Read channel messages 51 - `chat:write`—Send messages 52 - `im:history`—Read direct messages 53 - `im:write`—Send direct messages 54 - `users:read`—Read user information 55 5. Navigate to Event Subscriptions and enable events. Subscribe to bot events: 56 - `app_mention`—When the bot is mentioned 57 - `message.channels`—Messages in public channels 58 - `message.im`—Direct messages to the bot 59 6. Install the app to your workspace. Save the Bot User OAuth Token (starts with `xoxb-`) 60 61 ## Creating a Slack Gateway 62 63 You create Slack gateways through the Gateways section in the Agent Mesh Enterprise web interface. Navigate to Gateways and click the Create Gateway button, then select "Slack" as the gateway type. 64 65 ### Configuration Fields 66 67 The Slack gateway creation form requires the following information: 68 69 #### Basic Details 70 71 Provide a unique gateway name (3–255 characters) and a description of its purpose (10–1000 characters). 72 73 #### Slack Configuration 74 75 ##### Bot Token 76 77 The Bot User OAuth Token from your Slack App. This token must start with `xoxb-` and is used to authenticate API calls for sending messages and accessing Slack resources. 78 79 Example: `xoxb-your-bot-token` 80 81 ##### App Token 82 83 The App-Level Token from your Slack App's Socket Mode configuration. This token must start with `xapp-` and is used to establish the Socket Mode WebSocket connection. 84 85 Example: `xapp-your-app-token` 86 87 ##### Default Agent 88 89 The agent that handles incoming messages. Select from available deployed agents in your Agent Mesh deployment. This field is optional—if you do not select an agent, messages are routed to the Orchestrator, which determines the appropriate agent based on the message content. 90 91 ### Example Configuration 92 93 The following example shows a configuration for a Slack gateway: 94 95 Basic Details: 96 - Name: `Engineering Support Bot` 97 - Description: `Slack bot for the engineering team to interact with documentation and code analysis agents` 98 99 Slack Configuration: 100 - Bot Token: `xoxb-...` (from Slack App OAuth settings) 101 - App Token: `xapp-...` (from Slack App Socket Mode settings) 102 - Default Agent: `engineering-assistant` 103 104 ## After Creating the Gateway 105 106 After you save the gateway, it appears in the Gateways list with "Not Deployed" status. You can edit, download the YAML configuration, or deploy it. Once deployed, the gateway connects to Slack through Socket Mode and users can interact with the bot by mentioning it in channels or sending direct messages. For details on deployment, states, and lifecycle management, see [Gateways](gateways.md). 107 108 ## How Message Processing Works 109 110 The following diagram shows the message processing flow when a user sends a message to the Slack bot. 111 112 ```mermaid 113 sequenceDiagram 114 participant User as Slack User 115 participant Slack as Slack Platform 116 participant Gateway as Slack Gateway 117 participant Mesh as Agent Mesh 118 participant Agent as Default Agent 119 120 User->>Slack: Send Message 121 Slack->>Gateway: Socket Mode Event 122 Gateway->>Gateway: Parse Message 123 Gateway->>Gateway: Build Stimulus 124 Gateway->>Mesh: Send Stimulus 125 Mesh->>Agent: Route to Agent 126 Agent->>Agent: Process Request 127 Agent->>Mesh: Return Response 128 Mesh->>Gateway: Deliver Response 129 Gateway->>Slack: Post Reply 130 Slack->>User: Display Reply 131 ``` 132 133 ## Security Considerations 134 135 ### Token Security 136 137 Slack tokens provide access to your workspace. These tokens are stored encrypted, redacted from API responses, and injected at deployment time through Kubernetes Secrets. For more details on credential handling, see [Gateways](gateways.md). 138 139 :::warning[Token Security] 140 Never commit downloaded YAML files containing actual tokens to version control. Never share Bot or App tokens publicly. If tokens are compromised, regenerate them immediately in your Slack App settings. 141 ::: 142 143 ### Workspace Access 144 145 The Slack bot has access to messages in channels where it has been added and direct messages sent to it. Consider the following: 146 147 - Only add the bot to channels where agent access is appropriate 148 - Users should be aware that messages to the bot are processed by Agent Mesh 149 - The bot's responses may contain information from connected data sources 150 151 ### Token Rotation 152 153 If you need to rotate Slack tokens: 154 155 1. Generate new tokens in your Slack App settings 156 2. Update the gateway configuration with new tokens 157 3. Deploy the gateway update 158 4. Revoke the old tokens in Slack 159 160 ## Troubleshooting 161 162 ### Gateway Shows Disconnected 163 164 A deployed gateway shows "Disconnected" connection status. 165 166 This issue can occur when the gateway pod crashed or was evicted, when the Bot Token or App Token is invalid, when Socket Mode is not enabled in the Slack App, or when there are network connectivity issues to Slack. 167 168 To resolve this issue: 169 1. Check Kubernetes pod status: `kubectl get pods | grep gateway` 170 2. Check pod logs: `kubectl logs <pod-name>` 171 3. Verify tokens are correct and start with expected prefixes 172 4. Confirm Socket Mode is enabled in your Slack App settings 173 5. Consider undeploying and redeploying the gateway 174 175 ### Bot Not Responding to Messages 176 177 Users send messages to the bot but receive no response. 178 179 This issue can occur when the bot is not added to the channel, when event subscriptions are not configured, when the default agent is not deployed, or when message events are not reaching the gateway. 180 181 To resolve this issue: 182 1. Ensure the bot is added to channels where users are messaging 183 2. Verify Event Subscriptions are configured in the Slack App 184 3. Check that the default agent is deployed and responding 185 4. Review gateway logs for incoming events 186 187 ### Authentication Errors 188 189 Gateway logs show authentication or token errors. 190 191 This issue can occur when tokens are invalid or expired, when tokens are from different Slack Apps, or when the incorrect token type is used (such as using an App Token where a Bot Token is expected). 192 193 To resolve this issue: 194 1. Verify Bot Token starts with `xoxb-` 195 2. Verify App Token starts with `xapp-` 196 3. Ensure both tokens are from the same Slack App 197 4. Regenerate tokens if they may have been revoked 198 199 ### Missing Permissions 200 201 The bot can connect but cannot read messages or send replies. 202 203 This issue can occur when OAuth scopes are missing on the Bot Token, or when the app was not reinstalled after adding scopes. 204 205 To resolve this issue: 206 1. Review required scopes in the Prerequisites section 207 2. Add any missing scopes in Slack App OAuth settings 208 3. Reinstall the app to your workspace to apply new scopes