← Back to Blog

Connect OE Runtime to Slack — AI Bot in 10 Minutes - Run Hello World Agent

Create a Slack app, paste a webhook URL, and your entire OE agent library is available inside Slack. Any message triggers your default agent. Named commands run specific ones. Manual approval chains pause and wait for your reply — right inside the channel.

What You Will Build

A Slack bot powered by OE Runtime that lives in your workspace. Once connected:

• Any message you send routes to your default conversational agent
• run hello — runs a named agent from your project
• agents — lists all available agents
• help — shows all supported commands
• yes / no — approve or reject a pending manual chain

What You Need

• A Slack workspace where you can install apps
• Node.js 18+ for npx
• An API key from OpenAI, Anthropic, or any supported LLM provider
• An OE Runtime project folder with at least one agent YAML

---

Step 1

Create a Slack App

Go to api.slack.com/apps and click Create New App. Choose From scratch, give it a name (e.g. OE Bot), and select your workspace.

Once created you land on the app's Basic Information page. Keep this tab open — you will come back to it several times during setup.

---

Step 2

Add Bot Token Scopes

In the left sidebar click OAuth & Permissions. Scroll down to Bot Token Scopes and add all six of these:

• chat:write — lets the bot send messages to channels and DMs
• channels:history — lets the bot read channel messages (required to receive events)
• im:history + im:read + im:write — lets the bot send and receive direct messages
• channels:read — lets the bot see which channels it belongs to

---

Step 3

Install the App and Copy the Bot Token

Still on the OAuth & Permissions page, scroll up and click Install to Workspace. Slack will ask you to confirm the permissions — click Allow.

After installation, the page shows your Bot User OAuth Token — it starts with xoxb-. Copy it. You will paste it into oe-config.json in the next step.

---

Step 4

Create oe-config.json

In your OE project folder, open oe-config.json and add the Slack connector. Leave publicUrl blank for now — you will fill it in after the Cloudflare tunnel starts.

oe-config.json

{
  "llm": {
    "provider": "openai",
    "model": "gpt-4o",
    "apiKey": "sk-..."
  },
  "server": {
    "enabled": true,
    "port": 3333,
    "publicUrl": "",
    "webhook": true
  },
  "connectors": [
    {
      "connection_name": "My Slack Bot",
      "connection_type": "slack",
      "botToken": "xoxb-YOUR-BOT-TOKEN",
      "auto_reply": true,
      "rate_limit": { "messages_per_minute": 10 },
      "history": { "enabled": true, "max_messages": 10 }
    }
  ]
}

Replace sk-... with your LLM API key and xoxb-YOUR-BOT-TOKEN with the token you copied in Step 3.

---

Step 5

Create the hello-world Skill

Create a hello-world/ folder in your project and add a SKILL.md inside it. This is the first skill you will call from Slack to confirm everything is working. Also create a root agent.yaml that lists it:

hello-world/SKILL.md

---
name: hello-world
description: Greets the user and shares a fun fact about today in history. Use to verify your Slack bot is connected and responding.
license: Apache-2.0
metadata:
  author: Open Enthrium
  version: "1.0"
---

You are a friendly, concise AI assistant.

## Step 1: Greet
Say hello, mention today's date, and share one fun fact about today in history. Keep it brief.

agent.yaml

name: Hello World Slack Bot
description: Slack bot with a hello-world skill.

skills:
  - path: ./hello-world
    trigger_type: auto
    default: true

---

Step 6

Start a Cloudflare Tunnel

Slack needs a public HTTPS URL to deliver events to your server. Cloudflare Tunnel gives you one for free — no account or signup needed.

npx cloudflared tunnel --url http://localhost:3333

You will see a URL like this appear in the output:

Copy that URL and keep this terminal open — the tunnel must stay running while you test.

---

Step 7

Update publicUrl in oe-config.json

Open oe-config.json and paste the Cloudflare URL into publicUrl:

"publicUrl": "https://purple-mouse-1234.trycloudflare.com"

This tells OE Runtime what public address to advertise as the Slack webhook URL. You will start the server in Step 11 after finishing the Slack configuration.

---

Step 8

Disable Socket Mode

This is the most commonly missed step. When you create a Slack app using certain templates, Socket Mode is enabled by default. When Socket Mode is ON, Slack uses a WebSocket connection instead of HTTP webhooks — it ignores the Event Subscriptions URL entirely, even if it shows Verified ✓. Your server will never receive any messages.

1. In the left sidebar click Socket Mode
2. Toggle Enable Socket Mode: OFF

---

Step 9

Configure Event Subscriptions

In the left sidebar click Event Subscriptions.

1. Toggle Enable Events to ON
2. Jump ahead to Step 11 to start the OE Runtime server — Slack will send a live challenge request the moment you paste the URL, so the server must be running before you proceed
3. Once the server is up, paste the webhook URL printed in your terminal into the Request URL field:

   https://purple-mouse-1234.trycloudflare.com/webhook/slack

4. Slack will immediately send a challenge request to verify the URL. Your OE server responds automatically — you will see Verified ✓ within a few seconds.

---

Step 10

Subscribe to Bot Events

Still on the Event Subscriptions page, scroll down to Subscribe to bot events and click Add Bot User Event. Add both of these:

• message.channels — fires when someone sends a message in a channel the bot is in
• message.im — fires when someone sends the bot a direct message

Click Save Changes. Slack will prompt you to reinstall the app — click reinstall your app and go through the confirmation. This regenerates the bot token. Copy the new xoxb- token from the OAuth & Permissions page and update botToken in your oe-config.json.

While you're in the Slack app settings, also enable direct messages to the bot:

1. In the left sidebar click App Home
2. Scroll to the Messages Tab section
3. Tick "Allow users to send Slash commands and messages from the messages tab"

This lets users DM the bot directly without a channel invite.

---

Step 11

Start the Server

Open a second terminal (keep the Cloudflare one running). Navigate to your project folder — the folder that contains agent.yaml and oe-config.json — then start OE Runtime in server mode:

cd path/to/your-project-folder
npx -y @openenthrium/oe-runtime@latest --serve --config oe-config.json

The server must be started from the same folder as agent.yaml so it can discover the skills listed inside it.

You now have three terminals running: Cloudflare tunnel, OE Runtime server, and your regular shell. Keep all three open.

---

Step 12

Test in Slack

Invite the bot to a channel first:

/invite @OE Bot

Then send commands as plain text — no slash needed. Start with the hello-world skill you created in Step 5:

Commands Reference

Type this in Slack	What it does
help	Show all supported commands
skills	List all available skills in your project
run <skill-name>	Run a named skill from your agent.yaml
status	Health check — LLM, connectors, uptime
yes / no	Approve or reject a pending manual chain
Any plain message	Routes to the default: true agent

Troubleshooting

Events verified ✓ but server terminal shows nothing

Socket Mode is enabled. Go to Socket Mode in the left sidebar and toggle it OFF. This is the most common cause — when Socket Mode is on, Slack uses WebSockets instead of HTTP webhooks and the Request URL is never called, even if it shows Verified ✓.

Bot does not respond to messages

Check that Event Subscriptions shows Verified ✓ and that message.channels is listed under bot events. Also confirm the bot has been invited to the channel with /invite @OE Bot.

"Sending messages to this app has been turned off"

Go to App Home → Messages Tab → tick "Allow users to send Slash commands and messages from the messages tab". This only affects DMs — channel messages are not affected.

Verified ✓ shows a red error instead

Your OE server is not reachable. Make sure both terminals are running — the Cloudflare tunnel and the OE Runtime server. If the tunnel URL changed (it changes every time you restart it), update publicUrl in oe-config.json, restart the server, and paste the new URL in Event Subscriptions.

Commands return "is not a valid slash command"

You typed a command starting with /. Slack intercepts those. Type without the slash: run hello instead of /run hello.