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:
Replace both token values with your own.
6

Restart the daemon

Apply the new configuration:
Or run directly:

​
Configuration fields

​
boolean
required
Set to true to activate the Slack gateway. Defaults to false.
​
string
required
Your Slack Bot User OAuth Token. Starts with xoxb-. Used to post messages and interact with the Slack Web API.
​
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.