Configure Channel - Slack

Slack uses a Bot Token and an App Token to connect Hermes Agent to team channels, direct messages, and automated task notifications.

This page covers

Creating a Slack app and configuring Socket Mode, permissions, and events
Binding the Slack Bot Token and App Token in LightVela
Chatting with Hermes Agent through Slack channels and direct messages

Steps

1. Open the Slack channel settings in LightVela

Sign in to the LightVela international site, open My Hermes → Channel, find the Slack card, and click + Connect. You will return with two credentials:

Slack Bot Token: starts with xoxb-.
Slack App Token: starts with xapp-.

2. Create a Slack app

Open Slack API Apps and sign in.
Click Create New App.

Create a new app from Slack API Apps

Select From scratch.

Select From scratch to create the Slack app

Enter an app name such as Hermes Agent.
Select the workspace where Hermes Agent should run, then click Create App.

Name the Slack app and select a workspace

If the workspace is missing, verify that the current Slack account belongs to it and can create apps.

3. Create the App Token

The App Token establishes the Socket Mode WebSocket connection. It must include the connections:write scope.

In the Slack app sidebar, open Settings → Basic Information.

Open Basic Information in the Slack app

Scroll to App-Level Tokens and click Generate Token and Scopes.

Generate an app-level token

Enter a recognizable token name, such as HermesSocket.
Click Add Scope.

Add a scope to the App Token

Search for and select connections:write.

Select the connections write scope

Confirm the scope is listed, then click Generate.

Generate the App Token with connections write

Copy the generated xapp-... token and store it securely. Click Done after copying it.

Copy the Slack App Token

Do not paste the App Token into the Bot Token field. A Client Secret or Signing Secret is not a replacement for this token.

4. Configure Socket Mode, permissions, and events

4.1 Enable Socket Mode

Open Settings → Socket Mode.
Turn on Enable Socket Mode.

Enable Slack Socket Mode

Socket Mode sends Slack events to Hermes Agent over WebSocket. This setup does not require an Event Subscriptions Request URL or an OAuth Redirect URL.

4.2 Add Bot Token Scopes

Open Features → OAuth & Permissions.
Scroll to Scopes → Bot Token Scopes.
Click Add an OAuth Scope.

Add a bot scope in OAuth and Permissions

Add scopes for the interaction modes you need:

Scope	Required for	Purpose
`app_mentions:read`	Channel use	Receive messages that mention the bot
`channels:read`	Public channels	Read basic public-channel information
`channels:history`	Public channels	Read messages in public channels the bot has joined
`chat:write`	All replies	Send messages as the bot
`im:read`	Direct messages	Read direct-message conversation information
`im:history`	Direct messages	Read direct messages sent to the bot
`im:write`	Direct messages	Open or manage direct-message conversations
`groups:read`	Optional private channels	Read private-channel information
`groups:history`	Optional private channels	Read messages in private channels the bot has joined

Review the Slack Bot Token Scopes

Only add the two groups:* scopes when private-channel access is required. The app must still be invited to each target channel.

4.3 Enable direct messages in App Home

If users should be able to message Hermes Agent directly:

Open Features → App Home.
Scroll to Show Tabs.
Enable Messages Tab.
Enable the option that allows users to send messages from the Messages tab.

If you only use channel mentions, you can skip this section and omit the im:* scopes and message.im event.

Open Features → Event Subscriptions.
Turn on Enable Events.
Under Subscribe to bot events, click Add Bot User Event.
Add app_mention for channel mentions.
Add message.im if direct messages are enabled.
Click Save Changes.

Configure Slack bot event subscriptions

If you change scopes or events after installation, return to OAuth & Permissions and click Reinstall to Workspace. New permissions do not take effect until the app is reinstalled.

5. Install the app and copy the Bot Token

Return to Features → OAuth & Permissions.
Click Install to Workspace. If the app is already installed, click Reinstall to Workspace.

Install the Slack app to the workspace

Review the requested permissions and click Allow.

Authorize the Slack app permissions

After Slack returns to OAuth & Permissions, find OAuth Tokens for Your Workspace.
Copy the Bot User OAuth Token that starts with xoxb-.

Copy the Slack Bot User OAuth Token

Do not use a Signing Secret, Client Secret, Verification Token, or an xoxp-... User OAuth Token. LightVela requires one xapp-... App Token and one xoxb-... Bot Token.

6. Bind Slack in LightVela

Return to My Hermes → Channel → Slack.
Paste the xoxb-... token into Slack Bot Token.
Paste the xapp-... token into Slack App Token.
Confirm that the tokens are in the correct fields, then submit the connection.
Wait for the Slack card to show as connected.

7. Test Hermes Agent in Slack

7.1 Test a channel mention

Open the Slack channel where you want to use Hermes Agent.
Invite the app:

/invite @Hermes Agent

Send a message that mentions the bot:

@Hermes Agent Summarize the key points discussed in this channel today.

The bot only receives channel messages after it has joined that channel.

7.2 Test a direct message

Open the new app from the Apps section in Slack.
Select the Messages tab.
Send a short message such as Hello.

Test a direct message in Slack App Home

Success state

The setup is complete when all applicable checks pass:

The Slack card in LightVela shows as connected.
The Slack app is installed in the target workspace.
Hermes Agent replies to a mention in a channel the app has joined.
When App Home and IM permissions are enabled, Hermes Agent replies to a direct message.

Supported message types

After Slack is connected, the channel supports these messaging scenarios:

Slack message type	Supported
Receive text mentions in channels	✅ Supported
Receive direct-message text in App Home	✅ Supported
Reply with text in channels and direct messages	✅ Supported
Send proactive messages, such as automated task notifications	✅ Supported

FAQ

Issue	Possible cause	Resolution
App Token is rejected	Wrong token type or missing `connections:write`	Generate a new `xapp-...` token under Basic Information → App-Level Tokens
Bot Token is rejected	A User OAuth Token or another credential was copied	Copy the `xoxb-...` Bot User OAuth Token from OAuth & Permissions
Event Subscriptions asks for a Request URL	Socket Mode is disabled	Enable Settings → Socket Mode, then return to Event Subscriptions
Channel mentions are not received	App is not in the channel, scopes are missing, or `app_mention` is absent	Invite the app, add channel scopes and `app_mention`, then reinstall the app
Direct messages are not received	Messages Tab is disabled, IM scopes are missing, or `message.im` is absent	Enable Messages Tab, add `im:*` and `message.im`, then reinstall the app
New permissions do not work	App was not reinstalled after a change	Click Reinstall to Workspace under OAuth & Permissions
The channel is connected but there is no reply	Model unavailable, insufficient credits, or Agent status issue	Check Configure Models, instance status, and available credits

Next steps

Configure Channel - Telegram — Personal conversations and group notifications
Configure Channel - WhatsApp — International user communication and customer service
Configure Channel - Discord — Community operations and developer communities
Configure Automations — Send scheduled reminders and task results to Slack
Configure Skills — Extend Hermes Agent capabilities

Slack

On this page