Socket Mode lets you develop and test the Slack integration locally without exposing a public URL. Slack connects to your app over a WebSocket, so there is no need for ngrok or other tunneling tools.
Prerequisites
- A Slack app configured with Socket Mode enabled (in the Slack API dashboard under Settings > Socket Mode).
- An app-level token (
xapp-...) with the connections:write scope.
- The Exante backend running locally.
Environment variables
Add these to your .env file:
SLACK_CLIENT_ID=your_slack_app_client_id
SLACK_CLIENT_SECRET=your_slack_app_client_secret
SLACK_SIGNING_SECRET=your_slack_signing_secret
SLACK_APP_TOKEN=xapp-your-app-level-token
SLACK_SOCKET_MODE=true
| Variable | Description |
|---|
SLACK_CLIENT_ID | OAuth client ID from your Slack app settings |
SLACK_CLIENT_SECRET | OAuth client secret from your Slack app settings |
SLACK_SIGNING_SECRET | Signing secret for webhook signature verification |
SLACK_APP_TOKEN | App-level token (xapp-...) for Socket Mode |
SLACK_SOCKET_MODE | Set to true to enable Socket Mode |
Starting Socket Mode
Run the dedicated Flask CLI command:
FLASK_APP=app flask slack-dev
Socket Mode runs in a dedicated process. Do not start it inside Flask web workers or RQ workers — this would create duplicate WebSocket connections.
Testing events
Once Socket Mode is running:
- Open your Slack workspace.
- Mention the bot with
@Exante in any channel linked to an organization.
- Paste an Exante URL to test link unfurling.
- Check the terminal output for event processing logs.
Manifest management
The Slack app manifest is stored at app/domains/integrations/slack/manifest.yaml. To verify your local app config matches the deployed manifest:
- Export the live manifest from the Slack API dashboard (Settings > App Manifest).
- Compare it against
manifest.yaml using a diff tool.
- If they diverge, update either the manifest file or the Slack dashboard to match.
You can also use the Slack CLI to export the manifest:slack manifest export --app-id YOUR_APP_ID
Troubleshooting
| Symptom | Cause | Fix |
|---|
SLACK_APP_TOKEN is required | Missing app-level token | Generate one in Slack app settings |
Connection refused on startup | Redis or database not running | Start all services with make up |
| Events not arriving | Socket Mode not enabled in Slack | Enable in Slack API dashboard |
| Bot not responding to mentions | Channel not mapped to an organization | Map the channel to your organization |
| Link previews not showing | unfurl_domains not configured | Add app.exante.com in Slack app settings |
