Documentation Sync

This page translates plugins/adapters/slack/README.md. Keep this English page aligned with the README; pnpm sync:adapter-docs updates the Chinese pages.

@zhin.js/adapter-slack

Zhin.js Slack adapter (Plugin Runtime). Prefers Socket Mode; can also send and receive messages via the Runtime Host HTTP Events API.

Features

• Socket Mode (default): persistent WebSocket connection, no public URL needed
• HTTP Events API: httpHostToken POST (signature verification), not legacy host-router/Koa
• Inbound via endpoint[endpointSpec].events.emit(...); outbound through the registered send hook -> chat.postMessage / Block Kit
• Convention-based defineAdapter / definePlugin (no usePlugin needed)
• Block Kit buttons, slash commands, message editing, emoji reactions, etc. (see tools/)

Installation

pnpm add @zhin.js/adapter-slack

Plugin Runtime

The owning Adapter manages desired accounts and running incarnations. The actual SDK or protocol Client implements structural Endpoint; framework hooks use endpointSpec without replacing native SDK APIs. Complete accepted callbacks enter through events.run(...) before deduplication and asynchronous normalization; see Adapter authoring.

• @zhin.js/adapter — convention-based adapters/slack/index.ts (defineAdapter)
• @zhin.js/core — endpoint[endpointSpec].events.emit(...) inbound, outboundMessageToken outbound
• @zhin.js/host-http — only needed for HTTP mode to register Events route via httpHostToken
• zhin.js — plugin.ts (definePlugin)
• Configuration goes to the top-level <instanceKey> block via the plugin's schema.json

Inbound: endpoint[endpointSpec].events.emit('message.receive', { conversation, message, content, sender, metadata }) (conversation.id is the channelId, threads land in conversation.threadId) Outbound: send({ conversation, payload }) -> Web API (conversation.id is the channel, conversation.threadId maps to thread_ts)

Platform Permissions (platform permit)

• plugin.ts has registered a checker. Runtime Tool permissions are uniformly enforced via Core's canAccessTool(). When Slack inbound does not have a reliable sender role, restricted tools are denied by fail-closed policy and will not silently pass through.

Mode Comparison

Mode	socketMode	Use Case	Additional Fields
Socket Mode (default)	true	Local / intranet, no public URL needed	appToken (xapp-...)
HTTP Events	false	Production with public HTTPS	signingSecret + Runtime Host

Prerequisites

1. Create a Slack App, install it to the Workspace, and grant the required OAuth scopes.
2. Socket Mode needs a connections:write App-Level Token; HTTP mode needs a Signing Secret and Events URL.
3. Subscribe to required bot events and invite the App to target channels.

Minimal Configuration (Socket Mode)

configVersion: 2
# zhin.config.yml (Plugin Runtime)
plugins:
  slack: "@zhin.js/adapter-slack"
slack:
  socketMode: true # default true, can be omitted
  endpoints:
    - name: my-slack-bot
      token: ${SLACK_BOT_TOKEN}
      appToken: ${SLACK_APP_TOKEN}

Multiple workspaces: a single plugin instance can attach multiple endpoints (each item in the endpoints array overrides top-level fields; name is required):

configVersion: 2
plugins:
  slack: "@zhin.js/adapter-slack"
slack:
  endpoints:
    - name: team-a
      token: ${SLACK_BOT_TOKEN_A}
      appToken: ${SLACK_APP_TOKEN_A}
    - name: team-b
      token: ${SLACK_BOT_TOKEN_B}
      appToken: ${SLACK_APP_TOKEN_B}

HTTP Events Configuration

configVersion: 2
plugins:
  slack: "@zhin.js/adapter-slack"
slack:
  socketMode: false
  webhookPath: /slack/events # optional, default /slack/events
  endpoints:
    - name: my-slack-bot
      token: ${SLACK_BOT_TOKEN}
      signingSecret: ${SLACK_SIGNING_SECRET}

The root plugin the main configuration plugins map (or project graph) must reference @zhin.js/adapter-slack (instanceKey: slack). In HTTP mode, the Runtime Host (http) must already be listening; the Slack App's Event Subscriptions / Interactivity / Slash Commands Request URL should point to https://your-domain/slack/events.

Environment Variables

Variable	Description
SLACK_BOT_TOKEN / SLACK_TOKEN	Bot User OAuth Token (xoxb-...)
SLACK_APP_TOKEN	App-Level Token (Socket Mode, xapp-...)
SLACK_SIGNING_SECRET	Signing Secret (HTTP mode)
SLACK_BOT_NAME	Optional endpoint name

Message Format

Outbound (Markdown -> mrkdwn)

Common Markdown (e.g., **bold**) is converted to Slack mrkdwn and sent via Block Kit section.

Inbound (mrkdwn -> Markdown)

Slack mrkdwn	Common Markdown
*bold*	**bold**
_italic_	*italic*
~strike~	~~strike~~
<url|text>	[text](url)

AI Tools

Category	Path
Permit vocabulary	PERMITS.md
Platform tools	tools/ (invite, topic, reactions, pin, edit, etc.)
Skill documentation	agents/slack/skills/slack-channels/SKILL.md and agents/slack/skills/slack-messages/SKILL.md、agents/slack/skills/slack-users/SKILL.md

Limitations

• Inbound mrkdwn -> Markdown conversion is heuristic
• Modals / Select menus — not yet supported
• OAuth installation flow — not yet supported
• Old usePlugin / extends Adapter / host-router production entry points have been removed

Console page

Open the Console Slack page (route /slack) to:

• view running connections and test connectivity;
• add, edit, start, stop, replace, or remove accounts through Host runtime storage; startup configuration and .env remain unchanged;
• complete LoginAssist tasks (QR code, slider or device confirmation) when the adapter asks for a login;

An administrator must review and confirm the existing account list before its first migration; identity and history are retained. New or replaced accounts are saved disabled and must be started explicitly. A connection update reconnects only that account; replacement uses a new internal identity and does not inherit Sessions or settings. If a commit outcome is unknown, refresh to verify it before taking another action.

Reading requires slack:read; writes require slack:write. A full admin token is unrestricted. "Add endpoint" is equivalent to the old slack endpoint add command.

Troubleshooting

Symptom	Check
Socket Mode cannot connect	xapp- token, Socket Mode, and connections:write scope
HTTP Events returns 401	Signing Secret, raw body, server clock, and reverse proxy
Channel event is missing	Event subscriptions, OAuth scopes, and App channel membership
Reply escapes the thread	Preserve inbound thread_ts as Conversation threadId

License

MIT

Group/channel-specific Skills and their private Tools are disclosed only in their declared scenes. Common lookup and messaging stay separate. See Agent capabilities for classification.