slack

# Slack API Emulator Fully stateful Slack Web API emulation with channels, messages, threads, reactions, user profiles, presence, modern file uploads, pins, bookmarks, views, OAuth v2, and incoming webhooks. Chat writes preserve common rich message fields such as `blocks`, `attachments`, `metadata`, formatting flags, unfurl flags, and client message ids. Conversation writes update archive state, names, topics, purposes, membership, DMs, MPIMs, and read cursors. User writes update profile fields, status, custom fields, and deterministic active or away presence. File writes support the current external upload flow with local upload URLs, file share messages, reads, lists, downloads, and deletes. Pin and bookmark writes support channel message pins and link bookmarks. View writes support App Home publishing and modal stacks. Seeded OAuth apps and OAuth installs create bot users and installation records. OAuth exchanges and explicit token seeds create scoped token records. State changes dispatch `event_callback` payloads to configured webhook URLs. Slack message text is limited to 40,000 Unicode characters across chat writes, incoming webhooks, and file upload initial comments. Longer text is truncated at a Unicode code point boundary before it is stored or dispatched. Successful Web API responses include `warning: "message_truncated"` and `response_metadata` with the matching warning and explanatory message. Rich fields such as `blocks` and `attachments` are preserved unchanged. ## Start Local listeners bind to `127.0.0.1` by default. For access from containers or other machines, pass `--host 0.0.0.0` to the CLI or `hostname: '0.0.0.0'` to `createEmulator`. Configure `--base-url` or `baseUrl` for advertised URLs reachable by those clients. ```bash # Slack only npx emulate --service slack # Default port (when run alone) # http://localhost:4000 ``` Or programmatically: ```typescript import { createEmulator } from 'emulate' const slack = await createEmulator({ service: 'slack', port: 4003 }) // slack.url === 'http://localhost:4003' ``` ## Auth Pass tokens as `Authorization: Bearer <token>`. All Web API endpoints require authentication. ```bash curl -X POST http://localhost:4003/api/auth.test \ -H "Authorization: Bearer test_token_admin" ``` Requests without a token return `not_authed`. In relaxed scope mode, any non-empty unknown bearer token maps to the first seeded user. Scope checks are relaxed by default for local development. Set `slack.strict_scopes: true` in seed config when you need supported Web API methods to return Slack-style `missing_scope` errors with `needed` and `provided` fields. Strict mode checks `chat:write`, `channels:read`, `channels:history`, `channels:join`, `channels:manage`, `channels:write`, `groups:read`, `groups:history`, `groups:write`, `im:read`, `im:history`, `im:write`, `mpim:read`, `mpim:history`, `mpim:write`, `users:read`, `users:read.email`, `users.profile:read`, `users.profile:write`, `users:write`, `files:read`, `files:write`, `pins:read`, `pins:write`, `bookmarks:read`, `bookmarks:write`, `reactions:read`, `reactions:write`, `team:read`, and `admin.conversations:write`. Slack lists no method-specific scopes for `views.publish`, `views.open`, `views.update`, or `views.push`, so the emulator requires auth but does not add strict-scope checks for those methods. ## Pointing Your App at the Emulator ### Environment Variable ```bash SLACK_EMULATOR_URL=http://localhost:4003 ``` ### Slack SDK / Bolt ```typescript import { WebClient } from '@slack/web-api' const client = new WebClient(token, { slackApiUrl: `${process.env.SLACK_EMULATOR_URL}/api/`, }) ``` ### OAuth URL Mapping | Real Slack URL | Emulator URL | |----------------|-------------| | `https://slack.com/oauth/v2/authorize` | `$SLACK_EMULATOR_URL/oauth/v2/authorize` | | `https://slack.com/api/oauth.v2.access` | `$SLACK_EMULATOR_URL/api/oauth.v2.access` | ### Auth.js / NextAuth.js ```typescript { id: 'slack', name: 'Slack', type: 'oauth', authorization: { url: `${process.env.SLACK_EMULATOR_URL}/oauth/v2/authorize`, params: { scope: 'chat:write,channels:read,users:read,users.profile:read' }, }, token: { url: `${process.env.SLACK_EMULATOR_URL}/api/oauth.v2.access`, }, clientId: process.env.SLACK_CLIENT_ID, clientSecret: process.env.SLACK_CLIENT_SECRET, } ``` ## Seed Config ```yaml slack: team: name: My Workspace domain: my-workspace users: - name: developer real_name: Developer email: dev@example.com is_admin: true profile: title: Local Developer status_text: Testing locally status_emoji: ":computer:" presence: active - name: designer real_name: Designer email: designer@example.com profile: title: Designer presence: away channels: - name: general topic: General discussion - name: engineering topic: Engineering discussions is_private: true bots: - name: my-bot oauth_apps: - client_id: "12345.67890" client_secret: example_client_secret app_id: A000000001 name: My Slack App redirect_uris: - http://localhost:3000/api/auth/callback/slack scopes: - chat:write - channels:read - channels:history - channels:join - channels:manage - channels:write - groups:read - groups:history - groups:write - im:read - im:history - im:write - mpim:read - mpim:history - mpim:write - users:read - users:read.email - users.profile:read - users.profile:write - users:write - files:read - files:write - pins:read - pins:write - bookmarks:read - bookmarks:write - reactions:read - reactions:write - team:read user_scopes: - users:read - users.profile:read bot_name: my-bot tokens: - token: xoxb-local-test user: developer scopes: - chat:write - channels:read - channels:history - channels:join - channels:manage - channels:write - groups:read - groups:history - groups:write - im:read - im:history - im:write - mpim:read - mpim:history - mpim:write - users:read - users:read.email - users.profile:read - users.profile:write - users:write - files:read - files:write - pins:read - pins:write - bookmarks:read - bookmarks:write - reactions:read - reactions:write - team:read incoming_webhooks: - channel: general label: CI Notifications strict_scopes: false signing_secret: my_signing_secret ``` When no OAuth apps are configured, the emulator accepts any `client_id`. With apps configured, strict validation is enforced for `client_id`, `client_secret`, and `redirect_uri`. `signing_secret` signs every outbound event subscription callback. Configure the receiving app with the same secret; signed callbacks include `X-Slack-Request-Timestamp` and `X-Slack-Signature`, with `X-Slack-Signature` set to `v0=<HMAC-SHA256(secret, "v0:<timestamp>:<raw-body>")>`. Verify against the unparsed request body. When the secret is absent or empty, callbacks are unsigned. ## API Endpoints ### Auth ```bash # Test authentication curl -X POST http://localhost:4003/api/auth.test \ -H "Authorization: Bearer $TOKEN" ``` ### Chat `chat.postMessage`, `chat.update`, `conversations.history`, and `conversations.replies` round trip text plus common rich message fields: `blocks`, `attachments`, `metadata`, `mrkdwn`, `parse`, `link_names`, `unfurl_links`, `unfurl_media`, `username`, `icon_url`, `icon_emoji`, `bot_id`, `app_id`, `client_msg_id`, and `reply_broadcast`. `chat.postMessage` can also post to opened DM conversations or supported Slack user IDs. `chat.postEphemeral` stores ephemeral messages outside channel history. `chat.scheduleMessage`, `chat.deleteScheduledMessage`, and `chat.scheduledMessages.list` keep scheduled messages pending until deleted or inspected. ```bash # Post message curl -X POST http://localhost:4003/api/chat.postMessage \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"channel": "C000000001", "text": "Hello from the emulator!"}' # Post threaded reply curl -X POST http://localhost:4003/api/chat.postMessage \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"channel": "C000000001", "text": "Thread reply", "thread_ts": "1234567890.123456"}' # Post rich message curl -X POST http://localhost:4003/api/chat.postMessage \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"channel": "C000000001", "text": "Deploy complete", "blocks": [{"type": "section", "text": {"type": "mrkdwn", "text": "*Deploy* complete"}}], "metadata": {"event_type": "deploy_complete", "event_payload": {"deploy_id": "dep_123"}}, "unfurl_links": false}' # Update message curl -X POST http://localhost:4003/api/chat.update \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"channel": "C000000001", "ts": "1234567890.123456", "text": "Updated message"}' # Delete message curl -X POST http://localhost:4003/api/chat.delete \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"channel": "C000000001", "ts": "1234567890.123456"}' # Get message permalink curl -X GET 'http://localhost:4003/api/chat.getPermalink?channel=C000000001&message_ts=1234567890.123456' \ -H "Authorization: Bearer $TOKEN" # Post ephemeral message curl -X POST http://localhost:4003/api/chat.postEphemeral \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"channel": "C000000001", "user": "U000000001", "text": "Only you can see this"}' # Schedule message curl -X POST http://localhost:4003/api/chat.scheduleMessage \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d "{\"channel\": \"C000000001\", \"text\": \"Reminder\", \"post_at\": $(($(date +%s) + 3600))}" # List scheduled messages curl -X POST http://localhost:4003/api/chat.scheduledMessages.list \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"channel": "C000000001"}' # Delete scheduled message curl -X POST http://localhost:4003/api/chat.deleteScheduledMessage \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"channel": "C000000001", "scheduled_message_id": "Q123456789"}' # /me message curl -X POST http://localhost:4003/api/chat.meMessage \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"channel": "C000000001", "text": "is thinking..."}' ``` ### Conversations ```bash # List channels (cursor pagination) curl -X POST http://localhost:4003/api/conversations.list \ -H "Authorization: Bearer $TOKEN" # List DMs and MPIMs curl -X POST http://localhost:4003/api/conversations.list \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"types": "im,mpim"}' # Get channel info curl -X POST http://localhost:4003/api/conversations.info \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"channel": "C000000001"}' # Create channel curl -X POST http://localhost:4003/api/conversations.create \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "new-channel", "is_private": false}' # Archive and unarchive a non-general channel curl -X POST http://localhost:4003/api/conversations.archive \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"channel": "C000000002"}'