Skip to main content
This guide explains how to connect Oxy to Slack. Once configured, users can interact with Oxy by:
  • @mentioning the Oxy bot in channels
  • Using the /oxy slash command
  • Sending direct messages to the Oxy bot

​
Prerequisites

Before you begin, you’ll need:
  • An externally reachable HTTPS URL for your Oxy instance (e.g., https://oxy.yourcompany.com)
  • Admin rights for the Slack workspace you want to connect
For local development, you can use a tunneling service like ngrok to expose your local Oxy instance.

​
Setup

1

Create a Slack app from the manifest

  1. Go to Slack Apps and click Create New App
  2. Select From a manifest
  3. Choose your target workspace and click Next
  4. Switch to the YAML tab
  5. Copy the manifest below, replacing {{YOUR_OXY_BASE_URL}} with your Oxy base URL (e.g., https://oxy.yourcompany.com):
Slack App Manifest
display_information:
  name: Oxy AI
  description: Ask Oxy anything
  background_color: "#383838"
features:
  app_home:
    home_tab_enabled: true
    messages_tab_enabled: true
    messages_tab_read_only_enabled: false
  bot_user:
    display_name: Oxy
    always_online: false
  slash_commands:
    - command: /oxy
      url: "{{YOUR_OXY_BASE_URL}}/api/slack/commands"
      description: Ask Oxy
      should_escape: false
  assistant_view:
    assistant_description: Ask Oxy anything about your data
    suggested_prompts: []
oauth_config:
  scopes:
    bot:
      - app_mentions:read
      - assistant:write
      - channels:history
      - channels:read
      - chat:write
      - commands
      - groups:history
      - im:history
      - im:write
      - users:read
      - users:read.email
settings:
  event_subscriptions:
    request_url: "{{YOUR_OXY_BASE_URL}}/api/slack/events"
    bot_events:
      - app_mention
      - assistant_thread_context_changed
      - assistant_thread_started
      - message.channels
      - message.groups
      - message.im
  org_deploy_enabled: false
  socket_mode_enabled: false
  token_rotation_enabled: false
  1. Paste the modified manifest and click Next
  2. Review the scopes and click Create
2

Add Slack configuration to config.yml

Add the slack section to your config.yml:
config.yml
slack:
  default_agent: agents/my-agent.agent.yml
  bot_token_var: SLACK_BOT_TOKEN
  signing_secret_var: SLACK_SIGNING_SECRET
The default_agent is the Oxy agent that will respond to Slack @mentions and direct messages. Point this to an existing agent file in your project.
3

Copy the Signing Secret

  1. In the Slack app settings, go to Basic Information
  2. Under App Credentials, copy the Signing Secret
  3. Add the signing secret to your environment:
export SLACK_SIGNING_SECRET=your-signing-secret-here
Or add it to your .env file:
.env
SLACK_SIGNING_SECRET=your-signing-secret-here
Never commit your .env file or expose credentials in version control.
4

Install the app to your workspace

  1. In the left sidebar, go to OAuth & Permissions
  2. Under OAuth Tokens, click Install to Workspace and approve the permissions
If you’re not a workspace admin, you’ll see Request to Install instead. A workspace admin will need to approve the request.
  1. Copy the Bot User OAuth Token (starts with xoxb-)
  2. Add the bot token to your environment:
export SLACK_BOT_TOKEN=xoxb-your-token-here
Or add it to your .env file:
.env
SLACK_BOT_TOKEN=xoxb-your-token-here
  1. Restart your Oxy instance to pick up the bot token
5

Test the integration

  1. In Slack, invite the Oxy bot to a channel: /invite @Oxy
  2. Test with a mention: @Oxy what can you help me with?
  3. Or use the slash command: /oxy hello

​
Enable the AI Agent Sidebar

Slack provides a dedicated AI agent sidebar for chatting with assistants like Oxy. This needs to be enabled for users to access the DM experience.

​
For Workspace Admins

To enable the Oxy agent for all members in your workspace:
  1. Click your workspace name in the sidebar
  2. Select Tools & settings → Manage apps
  3. Find and select the Oxy AI app
  4. Click App settings
  5. Next to AI agent experience, click Edit
  6. Choose Enabled to display the agent to all members
  7. Click Save

​
For Individual Users

If not enabled workspace-wide, users can enable the agent in their personal preferences:
  1. Click your profile picture in the sidebar
  2. Select Preferences
  3. Go to the Navigation tab
  4. Under App agents & assistants, check Show app agents
  5. Check Oxy to display it in the sidebar
Slack Preferences showing App agents & assistants settings
Once enabled, click the agent icon in the top-right corner of Slack to open a chat with Oxy.
For more details, see Slack’s documentation on AI apps.

​
Configuration Options

OptionRequiredDescription
default_agentYesPath to the agent file used for Slack DM conversations and when no channel binding is set
bot_token_varYesEnvironment variable containing the Slack Bot User OAuth Token
signing_secret_varYesEnvironment variable containing the Slack Signing Secret
oxy_app_urlNoPublic URL of your Oxy instance. Enables “View in Oxy” links in Slack responses
When oxy_app_url is configured, agent responses in Slack will include a “View in Oxy” link. Clicking this link opens the conversation in the Oxy web app, where users can see:
  • SQL queries generated by the agent
  • Data tables and query results
  • Visualizations like charts
  • Other artifacts from the conversation
Since Oxy may run behind a reverse proxy, it cannot automatically determine its public URL. You must explicitly set oxy_app_url to the publicly accessible URL of your Oxy instance for these deep links to work correctly.
If oxy_app_url is not set, responses will not include “View in Oxy” links.

​
Example Configuration

config.yml
slack:
  default_agent: agents/analytics.agent.yml
  bot_token_var: SLACK_BOT_TOKEN
  signing_secret_var: SLACK_SIGNING_SECRET
  oxy_app_url: https://oxy.yourcompany.com  # Enables "View in Oxy" deep links

​
Channel Bindings

By default, all channels use the default_agent specified in your config. You can bind specific channels to different agents using the /oxy bind command: 
/oxy bind <agent_id>
For example: 
/oxy bind agents/sales.agent.yml
To remove a binding and revert to the default agent: 
/oxy unbind

​
Troubleshooting

  • Can’t find the Oxy agent in Slack: Enable it in Preferences → Navigation → App agents & assistants (see Enable the AI Agent Sidebar)
  • Bot doesn’t respond: Verify your SLACK_BOT_TOKEN and SLACK_SIGNING_SECRET are set correctly
  • URL verification failed: Ensure your Oxy instance is running and publicly accessible at the URL specified in the manifest. In your Slack app settings, go to Event Subscriptions and check that the Request URL shows “Verified”. If not, click Retry to re-verify. This is often necessary after changing the request URL in the manifest or on that page.
  • Permission errors: Check that the bot has been invited to the channel with /invite @Oxy
  • Signature verification failed: Confirm the signing secret matches between Slack and your environment