Skip to content

Slack bots

A bot in Slack answers whoever mentions it, with whatever they paste in. Send its model calls through the gateway and each answer is checked against your policies (guardrails see what people paste), charged to the right team and recorded in Request logs, and the bot can use Claude or Gemini as well as OpenAI's models.

What it is

A Slack bot is your own code, usually built with Slack's Bolt framework (Python or JavaScript), that receives events from Slack and calls a model to answer. The gateway carries that model call: point the model SDK the bot uses at the gateway and nothing else changes. This also holds for an app built on Slack's AI app features (the assistant side panel): its answers come from your code's model calls.

Slack's own AI features, and other companies' agents installed in Slack, call their own models. They don't go through the gateway.

The two settings

The two settings belong to the model SDK inside the bot, not to Slack:

Setting Environment variable Value
Base address OPENAI_BASE_URL https://<your-gateway>/v1
Key OPENAI_API_KEY Your Vidai key (starts vk_), never a provider's key

Keep them, and Slack's own tokens (SLACK_BOT_TOKEN, and SLACK_APP_TOKEN for Socket Mode), in your host's secret store, not in the code. The gateway's address is under Connect your app on the Keys page and in System › Settings › Gateway. You get the key from Keys › Issue a key; its secret is shown once.

A bot is a good fit for an agent's key: create an agent for the bot, issue its key, and its calls show under that agent and are charged to its team.

A minimal call

The Slack app needs the app_mentions:read and chat:write scopes, and the app_mention event. This bot uses Socket Mode, so it needs no public address.

import os
from openai import OpenAI
from slack_bolt import App
from slack_bolt.adapter.socket_mode import SocketModeHandler

app = App(token=os.environ["SLACK_BOT_TOKEN"])
llm = OpenAI()  # reads OPENAI_BASE_URL and OPENAI_API_KEY

@app.event("app_mention")
def answer(event, say):
    reply = llm.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": event["text"]}],
    )
    say(text=reply.choices[0].message.content, thread_ts=event.get("thread_ts", event["ts"]))

SocketModeHandler(app, os.environ["SLACK_APP_TOKEN"]).start()
import OpenAI from "openai";
import bolt from "@slack/bolt";

const app = new bolt.App({
  token: process.env.SLACK_BOT_TOKEN,
  appToken: process.env.SLACK_APP_TOKEN,
  socketMode: true,
});
const llm = new OpenAI(); // reads OPENAI_BASE_URL and OPENAI_API_KEY

app.event("app_mention", async ({ event, say }) => {
  const reply = await llm.chat.completions.create({
    model: "gpt-4o-mini",
    messages: [{ role: "user", content: event.text }],
  });
  await say({ text: reply.choices[0].message.content, thread_ts: event.thread_ts ?? event.ts });
});

await app.start();

The same code calls Claude or Gemini: put a name such as claude-sonnet-4.5 in model. The gateway translates the request for that provider and the answer back into the OpenAI shape. A bot written with the Anthropic SDK works too: see Anthropic SDK for Python.

Streaming

Slack messages are posted whole, so most bots don't stream. If yours updates a message as the answer arrives, stream as in OpenAI SDK for Python: a stream from Claude or Gemini arrives as OpenAI chunks.

Tool calls

A bot that looks things up (a ticket, an order) passes tools to the model and runs the ones the model calls. That works on every provider the gateway translates to, exactly as in OpenAI SDK for Python. In Request logs, the Tool filter under More filters finds the calls that offered or called a tool by its name.

Reading what the gateway did

Read the gateway's headers with with_raw_response, and log the reference beside the Slack message it answered:

raw = llm.chat.completions.with_raw_response.create(model="gpt-4o-mini", messages=messages)
print(raw.headers.get("x-vidai-request-id"))  # paste into Request logs › Request reference
reply = raw.parse()

Cost is never in the answer: find the call in Request logs.

Errors

The SDK raises its usual exceptions. Answer the user kindly and log the code:

import openai

try:
    reply = llm.chat.completions.create(model="gpt-4o-mini", messages=messages)
except openai.APIStatusError as e:
    code = e.response.headers.get("x-vidai-error-code")
    if code == "content_guardrail_blocked":
        say(text="I can't help with that message: it was stopped by your organisation's guardrails.")
    else:
        say(text="Something went wrong; please try again in a minute.")

The full list of codes is in the OpenAI SDK for Python page.

Model names

Use the names your organisation has approved, as listed under Models in the Control room. llm.models.list() returns exactly the models the bot's key may call.

What goes through the gateway

In Slack Through the gateway
Model calls your bot makes with an SDK pointed at the gateway Yes, to every provider your organisation has set up
Slack's own AI features (summaries, search answers) No
Other companies' agents and AI apps installed in your workspace No: they call their own models

Check it works in a minute

Start the bot and mention it in a channel it's in: "@yourbot reply with exactly: ok". It should answer ok in the thread. The call shows in Request logs within seconds.

Good to know

  • Slack expects an event to be acknowledged within 3 seconds; Bolt does that for you before your handler runs, so a slow model doesn't make Slack resend the event.
  • A bot installed in several workspaces can use one key per workspace, so each one's spend is apart.
  • The SDK retries twice by default; a fallback chain may already have tried another model before you see an error. Set max_retries=0 on the client if you don't want both.
  • The gateway's own 429 has no Retry-After header; back off on your side.