Slack Channel

Slack channels connect a Slack app to one Netmind Cloud Agent. NCA receives Slack Events API webhooks, verifies them with the app signing secret, and replies with the bot token.

NCA uses Slack Events API webhooks. It does not require Socket Mode or an xapp- app token.

Prerequisites

CHANNELS_ENABLED=true on the API service
PUBLIC_API_BASE_URL set to the public HTTPS base URL of the API service
An existing NCA agent
Permission to create or manage a Slack app in the workspace

Slack’s Request URL verification requires a public HTTPS URL. Localhost URLs will not verify unless they are exposed through a tunnel.

Create the Slack app

Open Slack API Apps.
Create an app from scratch.
Add a bot user under App Home.
Open OAuth & Permissions and add the bot scopes needed for your use case.

Recommended bot token scopes:

Scope	Why
`app_mentions:read`	Receive messages that mention the bot in channels.
`chat:write`	Send agent replies.
`im:history`	Receive direct messages.
`im:read`	Let the bot access DM conversations.
`im:write`	Let the bot send DMs.
`channels:history`	Optional, for public channel message events.
`groups:history`	Optional, for private channel message events.

Install the app to the workspace and copy the Bot User OAuth Token. It starts with xoxb-.

Configure in Admin

Open Admin, then go to Channels.
Create a new channel and choose Slack.
Select the agent that should receive messages.
Enter a label, the xoxb- bot token, and the signing secret from Basic Information.
Create the channel.
Copy the inbound URL from the channel detail page.

Paste the inbound URL into Slack Event Subscriptions as the Request URL:

{PUBLIC_API_BASE_URL}/api/channels/hooks/slack/{channelId}

Slack sends a url_verification request. When NCA verifies the signing secret and returns the challenge, the channel becomes active.

Event subscriptions

Enable Event Subscriptions and add these bot events:

Event	Why
`app_mention`	Messages in channels when users mention the bot.
`message.im`	Direct messages to the bot.

After changing scopes or event subscriptions, reinstall the Slack app to the workspace.

API payload

{
    "agentId": "agt_...",
    "provider": "slack",
    "label": "engineering-slack",
    "config": {
        "mentionOnly": true,
        "shareSessionInChannel": false,
        "threadIsolation": true,
        "progressMode": "preview"
    },
    "credentials": {
        "botToken": "xoxb-...",
        "signingSecret": "..."
    }
}

Send this body to POST /api/channels. NCA runs auth.test and stores the returned bot user ID and team ID in channel config.

Configuration

Field	Required	Default	Notes
`botUserId`	No	Auto-filled	Slack bot user ID returned by `auth.test`. Used to strip bot mentions from prompts.
`teamId`	No	Auto-filled	Slack workspace team ID returned by `auth.test`.
`mentionOnly`	No	`true`	In channels, only respond when the bot is mentioned. DMs always respond.
`shareSessionInChannel`	No	`false`	When `true`, users in the same channel share one agent session unless a thread scope is used.
`threadIsolation`	No	`true`	Uses Slack `thread_ts` as the session scope for threaded messages.
`progressMode`	No	`preview`	`preview` edits one progress message while the agent works. `final` only sends the final reply.

Credentials

Field	Required	Notes
`botToken`	Yes	Bot User OAuth Token. Must start with `xoxb-`. Stored encrypted.
`signingSecret`	Yes	App signing secret from Basic Information. Used to verify webhook signatures.

Verify

Use the channel detail page test action, or call:

curl -X POST "$NCA_API_URL/channels/{channelId}/test" \
    -H "Authorization: Bearer $NCA_TOKEN"

A healthy channel reports a passing auth.test result and an active channel status.

Troubleshooting

Request URL verification fails: check PUBLIC_API_BASE_URL, the signing secret, and that the request reaches /api/channels/hooks/slack/{channelId}.
Bot does not respond in DMs: subscribe to message.im and reinstall the app.
Bot does not respond in channels: subscribe to app_mention, invite the bot to the channel, and mention it.
Scope changes do not apply: reinstall the Slack app after changing scopes.