Skip to main content
The Slack gateway connects Hiroshi to your Slack workspace using Socket Mode, which means no public webhook URL is required. A persistent outbound WebSocket connection from Hiroshi to Slack’s servers handles all event delivery. Messages mentioning or sent directly to the bot are routed to the active agent, which replies back into the same conversation.

​
Prerequisites

  • A Slack app with Socket Mode enabled
  • An App-Level Token with the connections:write scope (required for Socket Mode)
  • Bot scopes: chat:write and app_mentions:read

​
Setup

1

Create a Slack app

Go to https://api.slack.com/apps and click Create New App. Choose From scratch, give it a name, and select the workspace you want to install it in.
2

Enable Socket Mode and generate an App-Level Token

In your app settings, navigate to Socket Mode and toggle it on. When prompted, generate an App-Level Token. Give it any label and add the connections:write scope. Copy the token — it starts with xapp-.
3

Add bot scopes

Navigate to OAuth & Permissions → Scopes → Bot Token Scopes and add:
  • chat:write — allows the bot to post messages
  • app_mentions:read — delivers events when the bot is mentioned
4

Install the app to your workspace

Navigate to Install App and click Install to Workspace. Authorise the requested permissions. After installation, copy the Bot User OAuth Token — it starts with xoxb-.
5

Edit config.toml

Open ~/.hiroshi/config.toml and add (or update) the [slack] section:
[slack]
enabled = true
bot_token = "xoxb-YOUR_BOT_TOKEN"
app_token = "xapp-YOUR_APP_TOKEN"
Replace both token values with your own.
6

Restart the daemon

Apply the new configuration:
hiroshi service restart
Or run directly:
hiroshi daemon

​
Configuration fields

​
enabled
boolean
required
Set to true to activate the Slack gateway. Defaults to false.
​
bot_token
string
required
Your Slack Bot User OAuth Token. Starts with xoxb-. Used to post messages and interact with the Slack Web API.
​
app_token
string
required
Your Slack App-Level Token. Starts with xapp-. Required to establish the Socket Mode WebSocket connection — without it, Hiroshi cannot receive events from Slack.
The Slack gateway maintains a persistent WebSocket connection for real-time event delivery with no polling delay. If the connection drops, the daemon will automatically reconnect using exponential backoff.