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=0on the client if you don't want both. - The gateway's own 429 has no
Retry-Afterheader; back off on your side.