Slack -- Team Communication Integration Expert

---

name: slack description: > Build Slack bots, webhook handlers, Block Kit layouts, and workflow automations. USE WHEN: User needs to implement Slack bots, webhooks, interactive messages, Block Kit, or workflow automations. DON'T USE WHEN: User needs general team communication strategy. Use Relay for notification design. Use Megaphone for announcements. OUTPUTS: Bot configurations, webhook handlers, Block Kit layouts, interactive message flows, workflow automations, OAuth installations. version: 1.0.0 author: SpookyJuice tags: [slack, bots, webhooks, block-kit, workflows, messaging] price: 14 author_url: "https://www.shopclawmart.com" support: "brian@gorzelic.net" license: proprietary osps_version: "0.1" content_hash: "sha256:014a3cc1c35204c600c45d27a4f732de8488123e9b17dfb60f22af48b1381a0d"

#‍​‌‌​‌‌‌‌​‌‌‌​​‌‌​‌‌‌​​​​​‌‌‌​​‌‌​​‌‌‌​‌​​​‌‌​​​‌​​‌‌‌​‌​​‌‌‌​​‌‌​‌‌​‌​‌​​​‌​‌‌​‌​​‌‌‌​​​​​‌‌​​​​​​‌‌​‌‌‌​‌‌​​‌‌​​​‌‌‌​​​​‌‌​​​‌‌​​‌‌​​‌‌​‌‌​​​‌‌‍ Slack

Version: 1.0.0 Price: $14 Type: Skill

Description

Production-grade Slack integration patterns for bots, interactive surfaces, and automations that hold up under real workspace traffic. Slack's platform spans three connection modes (HTTP, Socket Mode, OAuth), five interactive surfaces (messages, modals, Home tabs, shortcuts, workflow steps), and a Block Kit layout system with undocumented character limits and nesting constraints that the official builder tool won't warn you about. The real pain is operational: the 3-second response deadline that forces async architecture on every interaction handler, token scope sprawl across bot vs. user tokens, Events API retry storms that duplicate your side effects, and modal view_submission payloads that silently drop if your response shape is wrong.

Prerequisites

• Slack workspace with admin access (or permission to install apps)
• Slack App created at https://api.slack.com/apps
• Bot token: xoxb-... with appropriate scopes
• Signing secret for webhook verification
• For Socket Mode: App-level token (xapp-...)

Setup

1. Copy SKILL.md into your OpenClaw skills directory
2. Set environment variables:

   export SLACK_BOT_TOKEN="xoxb-..."
   export SLACK_SIGNING_SECRET="your-signing-secret"
   export SLACK_APP_TOKEN="xapp-..."  # Socket Mode only
   

3. Reload OpenClaw

Commands

• "Build a Slack bot that handles [use case]"
• "Create Block Kit layouts for [message type]"
• "Set up interactive modals for [workflow]"
• "Implement slash command handling for [command]"
• "Configure webhook listeners for [event types]"
• "Build a Slack Workflow step for [automation]"
• "Set up OAuth installation flow for [distribution model]"

Workflow

Bot Development

1. Connection mode selection — Socket Mode (WebSocket, no public URL, ideal for internal tools and development) vs. HTTP mode (requires public endpoint, needed for marketplace distribution). Choose Socket Mode unless you're distributing to external workspaces or need horizontal scaling behind a load balancer.
2. Event subscriptions — subscribe to events your bot needs: message.channels for public channel messages, message.im for DMs, app_mention for @-mentions, member_joined_channel for onboarding flows. Each event requires a corresponding bot token scope — message.channels needs channels:history, app_mention needs app_mentions:read.
3. Command handlers — register slash commands in the app config. Your handler receives a POST with command, text, user_id, channel_id, and a response_url. You must acknowledge within 3 seconds with a 200 response (empty body or immediate message), then use response_url to post the actual result asynchronously.
4. Message parsing and context — use blocks for rich formatting, text as the fallback for notifications. Thread replies use thread_ts to maintain conversation context. Track conversation state in your database keyed by channel_id + thread_ts, not by user ID alone — users can have multiple concurrent threads.
5. Middleware architecture — layer your handlers: authentication check (verify the request is from Slack), authorization (does this user have permission?), rate limiting (per-user cooldowns), then business logic. Bolt framework provides this middleware chain out of the box for Node.js and Python.
6. Error handling — Slack shows "dispatch_failed" to users if your handler crashes. Wrap every handler in try/catch, log the error with full context (user, channel, command), and return a user-friendly error message. Use response_type: 'ephemeral' for errors so only the triggering user sees them.

Interactive Messages

1. Block Kit surface selection — messages (persistent, editable, max 50 blocks), modals (form-like, up to 3 stacked, max 100 blocks), Home tab (per-user app landing page, max 100 blocks). Choose messages for notifications and status displays, modals for data collection, Home tab for dashboards.
2. Block Kit layout — compose layouts from blocks: section (text + optional accessory), actions (buttons, selects, date pickers), input (form fields, modal-only), divider, header, context (small metadata text), image. Text fields use mrkdwn (Slack's markdown variant, not standard markdown — no headings, no inline code blocks).
3. Action handlers — every interactive element needs a unique action_id. When a user clicks a button or selects an option, Slack POSTs to your interactivity URL with type: 'block_actions', the action_id, the triggering user, and the current value. Acknowledge within 3 seconds, then process.
4. Modal lifecycle — open with views.open (from a trigger like a slash command or shortcut), update with views.update (using the view_id from the original response), push with views.push (stacks a new modal, max 3 deep). On submit, you receive a view_submission payload — return { "response_action": "clear" } to close, "update" to refresh, or "errors" with field-level validation messages.
5. State management — use private_metadata (string, max 3000 chars) on modals to pass state between open/update/submit. For complex state, store in your database and put only a lookup key in private_metadata. Action payloads include block_id and action_id to identify which element was interacted with.
6. Dynamic options — selects and multi-selects can load options dynamically via options_load_url. Your endpoint receives the user's typed query and returns up to 100 matching options. Cache aggressively — this endpoint gets called on every keystroke with a 3-second timeout.

Webhook Integration

1. Incoming webhooks — the simplest integration: a unique URL that accepts POST requests with a JSON payload (text and/or blocks) and posts to a fixed channel. No authentication needed on the sender side. Use for CI/CD notifications, monitoring alerts, and one-way integrations that don't need interactivity.
2. Events API setup — configure your request URL in the app settings. Slack sends a url_verification challenge on first setup — respond with the challenge value. All subsequent events arrive as POST requests with type: 'event_callback', the event payload, and headers for signature verification.
3. Signature verification — every incoming request includes X-Slack-Signature and X-Slack-Request-Timestamp. Compute HMAC-SHA256(signing_secret, "v0:{timestamp}:{body}") and compare. Reject requests older than 5 minutes to prevent replay attacks. Never skip verification, even in development.
4. Retry handling — Slack retries failed event deliveries up to 3 times with X-Slack-Retry-Num and X-Slack-Retry-Reason headers. Return 200 immediately after receiving the event (before processing). If you need to deduplicate, track event_id values and skip already-processed events.
5. Rate limiting — the Events API delivers events at the rate they occur, but your app faces Web API rate limits when responding: Tier 1 methods (1 req/min), Tier 2 (20 req/min), Tier 3 (50 req/min), Tier 4 (100+ req/min). chat.postMessage is Tier 3 at ~1 per second per channel. Implement a token bucket queue for all outbound API calls.
6. Event filtering — subscribe only to events you handle. Each unnecessary subscription increases payload volume and retry traffic. Use event_authorizations to filter events from your own bot (prevent infinite loops). For high-volume workspaces, consider routing events to a message queue (SQS, Redis) before processing.

Workflow Builder

1. Custom workflow steps — register your app as a workflow step provider. Define: step name, input parameters (user-configurable in Workflow Builder UI), and outputs (data your step produces for downstream steps). Each step is a function that receives inputs, executes logic, and reports completion or failure.
2. Step execution flow — when a workflow triggers your step, Slack sends a workflow_step_execute event with workflow_step_execute_id and your configured inputs. Process the work, then call workflows.stepCompleted with output values, or workflows.stepFailed with an error message. You have 60 seconds to report completion.
3. Form inputs configuration — define what users see when configuring your step in Workflow Builder. Use Block Kit input blocks for text fields, selects, user pickers, and channel pickers. Variables from previous workflow steps are available as tokens (e.g., {{user.email}}) that Slack resolves at runtime.
4. External data integration — workflow steps can fetch data from external APIs, query databases, or trigger CI/CD pipelines. Structure your step as: validate inputs, call external service, map response to output variables, report completion. Handle external service timeouts with a retry strategy inside the 60-second window.
5. Error handling and retries — call workflows.stepFailed with a descriptive error message (shown to the workflow creator, not end users). For transient failures, implement internal retries before reporting failure. Log the workflow_step_execute_id for debugging failed runs.
6. Testing workflow steps — create a dedicated test workflow in a sandbox channel. Trigger it manually and verify: inputs arrive correctly, your logic executes, outputs propagate to downstream steps, and failures report meaningful messages. Test edge cases: empty inputs, long strings, special characters in variable values.

Output Format

SLACK -- IMPLEMENTATION GUIDE
Integration: [Bot/Interactive/Webhook/Workflow]
Connection: [Socket Mode/HTTP]
Date: [YYYY-MM-DD]

=== ARCHITECTURE ===
[Flow: event/command -> handler -> API call -> response]

=== APP CONFIGURATION ===
| Setting | Value | Scope/Permission |
|---------|-------|-----------------|
| [setting] | [value] | [required scope] |

=== EVENT SUBSCRIPTIONS ===
| Event | Handler | Response | Timeout |
|-------|---------|----------|---------|
| [event.type] | [handler] | [action] | [3s/60s] |

=== BLOCK KIT SURFACES ===
| Surface | Blocks | Max | Use Case |
|---------|--------|-----|----------|
| [surface] | [count] | [limit] | [purpose] |

=== TESTING CHECKLIST ===
- [Test scenario with expected behavior]

Common Pitfalls

• 3-second response deadline — slash commands, actions, and shortcuts must be acknowledged within 3 seconds or the user sees an error. Acknowledge immediately with a 200 response, then do your actual processing and use response_url or the Web API to deliver results asynchronously.
• Bot token vs. user token scope confusion — bot tokens (xoxb-) and user tokens (xoxp-) have different scope namespaces. channels:read on a bot token lists channels the bot is in; on a user token it lists all channels the user can see. Mixing them up causes silent permission failures.
• Events API retry storms — if your endpoint is slow or returns non-200, Slack retries the same event up to 3 times. Without deduplication on event_id, your handler processes the event multiple times, sending duplicate messages or triggering duplicate side effects.
• Socket Mode reconnection — WebSocket connections drop silently under network changes or after ~24 hours. The Bolt framework handles reconnection automatically, but custom implementations must detect disconnects and reconnect with exponential backoff. Lost events during disconnection are not replayed.
• Block Kit character limits — text objects in blocks have a 3000-character limit. section block text maxes at 3000 chars, context elements at 150. Modal private_metadata is 3000 chars. Exceeding any limit causes a silent failure with an unhelpful error message. Validate lengths before sending.
• Modal view_submission response format — returning the wrong JSON shape from a view_submission handler causes the modal to show a generic error with no debugging information. The response must be exactly { "response_action": "..." } — extra fields, wrong types, or missing keys all produce the same opaque failure.

Guardrails

• Never exposes tokens in client code. Bot tokens, signing secrets, and app-level tokens are server-only. Client-side code communicates through your backend, never directly with the Slack API using raw tokens.
• Webhook signatures always verified. Every incoming request validates the X-Slack-Signature header against your signing secret. Unverified requests are rejected before any processing occurs.
• Rate limits enforced at the queue level. All outbound Slack API calls route through a rate-limited queue that respects per-method tier limits. No burst sending that triggers 429 responses and temporary API blocks.
• Bot loop prevention. Every event handler checks bot_id on incoming messages and ignores events from the bot itself. No infinite message loops between the bot and its own responses.
• Sensitive data excluded from messages. Credentials, internal IDs, and PII are never included in Slack messages or Block Kit payloads. Slack messages are stored in Slack's infrastructure and visible to workspace admins.
• Scopes follow least privilege. The app requests only the OAuth scopes required for its functionality. No blanket admin scopes or unnecessary users:read.email access unless the feature explicitly requires it.

Support

Questions or issues with this skill? Contact brian@gorzelic.net Published by SpookyJuice — https://www.shopclawmart.com