Skip to main content

​
Connecting Lyzr Agents to Slack: A Cookbook

This guide walks you through deploying a Lyzr AI agent as a Slack bot. Once configured, users can DM your bot directly and get responses from your agent.

​
Prerequisites

  • A Lyzr account with an agent already created
  • A Slack workspace where you have permission to install apps

​
How It Works

User Message → Slack
                    ↓
             Lyzr Webhook receives it
                    ↓
             Agent runs inference
                    ↓
             Response sent back to user
Unlike Telegram, Slack requires you to manually register the Lyzr webhook URL inside your Slack App settings after creating the channel.

​
Step 1: Create a Slack App

  1. Go to api.slack.com/apps and click Create New App
  2. Choose From scratch
  3. Enter an app name and select your Slack workspace
  4. Click Create App

​
Step 2: Configure OAuth Scopes

  1. In your app settings, go to OAuth & Permissions in the left sidebar
  2. Scroll down to Bot Token Scopes and add the following scopes:
    ScopePurpose
    chat:writeSend messages back to users
    im:readRead direct messages
    im:historyAccess DM message history
  3. Scroll up and click Install to Workspace
  4. Click Allow on the permission screen
  5. Copy the Bot User OAuth Token — it starts with xoxb-: 
    xoxb-1234567890-1234567890123-AbCdEfGhIjKlMnOpQrStUvWx
💡 Save this as your bot_token.

​
Step 3: Get Your Signing Secret

  1. Go to Basic Information in the left sidebar
  2. Scroll down to App Credentials
  3. Copy the Signing Secret
💡 Save this as your signing_secret.

​
Step 4: Get Your Bot User ID

  1. Go to App Home in the left sidebar
  2. Scroll down to find the bot’s Member ID — it looks like U06MXDKMUUF
Alternatively: in Slack, open your bot’s profile → click the three-dot menu → Copy member ID

​
Step 5: Enable App Home Messaging

⚠️ This step is required. Without it, users will see “Sending messages to this app has been turned off” when trying to DM the bot.
  1. Go to App Home in the left sidebar
  2. Scroll to Show Tabs
  3. Enable Allow users to send Slash commands and messages from the messages tab
  4. Click Save Changes

​
Step 6: Create the Channel in Lyzr

  1. Open the Agent Builder page in the Lyzr UI
  2. Click the Channels button
  3. Click Configure next to Slack
  4. Fill in the form:
    FieldValue
    Bot Tokenxoxb-... token from Step 2
    Signing SecretSecret from Step 3
    Bot User IDMember ID from Step 4
    Default AgentSelect the agent you want to handle messages
  5. Click Create Channel
  6. A webhook URL will be displayed — copy it. It looks like: 
    https://your-server.com/v3/channels/webhook/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

​
Step 7: Register the Webhook URL in Slack

  1. Go back to api.slack.com/apps → your app
  2. Go to Event Subscriptions in the left sidebar
  3. Toggle Enable Events to ON
  4. Paste the webhook URL from Step 6 into the Request URL field
  5. Slack will immediately send a verification request — Lyzr handles this automatically. Wait for the ✓ Verified checkmark to appear
  6. Scroll down to Subscribe to bot events and add:
    • message.im — to receive direct messages sent to the bot
  7. Click Save Changes

​
Step 8: Reinstall the App

Any time you change scopes or events, Slack requires a reinstall to apply the changes.
  1. Go to OAuth & Permissions in the left sidebar
  2. Click Reinstall to Workspace
  3. Click Allow

​
Step 9: Test Your Bot

  1. In Slack, click Apps in the left sidebar (or search for your app name)
  2. Click your app to open a DM
  3. Send any message — your agent should reply within a few seconds

​
Linking Multiple Agents to a Channel

You can link more than one agent to a single channel. Users can then switch between agents using built-in commands.

​
Via the Lyzr UI

  1. Open Channels in the Agent Builder
  2. Click Manage agents on your configured channel
  3. Toggle agents on/off to link or unlink them
  4. Each linked agent gets a name used with the /switch command

​
Via the API

Add an agent: 
curl -X POST "https://your-server.com/v3/channels/{channel_id}/agents" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "67e4d6983e456a9f92912044",
    "name": "Support Agent"
  }'
Remove an agent: 
curl -X DELETE "https://your-server.com/v3/channels/{channel_id}/agents/{agent_id}" \
  -H "x-api-key: your-api-key"
The default agent cannot be removed. To change it, delete the channel and recreate it with a different default agent.

​
Bot Commands

Once multiple agents are linked, users can interact using these built-in commands:
CommandDescription
/agentsList all agents linked to this channel
/listSame as /agents
/switch <name>Switch to a different agent by name
Example: 
/agents
→ Available agents (use /switch <name> to select one):
  • Support Agent — 67e4d6983e456a9f92912044
  • Sales Agent — 67e4d6673e456a9f9291203d

/switch Sales Agent
→ Switched to agent 'Sales Agent'. How can I help you?
Agent selection is per-user and persistent — each person’s active agent is remembered across messages until they switch again.

​
Troubleshooting

​
”Sending messages to this app has been turned off”

Go to App Home → Show Tabs, enable Allow users to send Slash commands and messages from the messages tab, then reinstall the app.

​
Bot receives messages but doesn’t reply (502 error in logs)

Your bot_token is likely invalid or the chat:write scope is missing. Go to OAuth & Permissions, verify chat:write is listed under Bot Token Scopes, reinstall the app, and copy the fresh xoxb- token into Lyzr.

​
Slack verification fails when pasting the webhook URL

Your server must be publicly reachable at the moment you paste the URL — Slack sends a challenge request immediately. For local development, start ngrok first, then create the channel using the ngrok URL.

​
403 errors in logs after messages are sent

This usually means the channel was created before a recent migration. Delete and recreate the channel through the Lyzr UI.

​
”Your URL didn’t respond with the value of the challenge parameter”

The server is not running or not reachable. Confirm your ngrok tunnel or server is active and try again.

​
/switch command not working

Agent names are case-insensitive but must match exactly (ignoring leading/trailing spaces). Run /agents first to see the exact names available.