Discord bots¶
A community bot answers anyone who mentions it. Send its model calls through the gateway and each answer is checked against your policies, 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 Discord bot is your own code, built with a library such as discord.py or discord.js, that receives messages from Discord 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. Discord's own features, and other bots, don't go through the gateway.
The two settings¶
The two settings belong to the model SDK inside the bot, not to Discord:
| 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 the bot's own DISCORD_TOKEN, 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: its calls then show under that agent.
A minimal call¶
In the Discord Developer Portal, switch on the Message Content intent for the bot.
import os
import discord
from openai import AsyncOpenAI
llm = AsyncOpenAI() # reads OPENAI_BASE_URL and OPENAI_API_KEY
intents = discord.Intents.default()
intents.message_content = True
bot = discord.Client(intents=intents)
@bot.event
async def on_message(msg: discord.Message):
if msg.author == bot.user or bot.user not in msg.mentions:
return
reply = await llm.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": msg.clean_content}],
)
await msg.reply(reply.choices[0].message.content[:2000])
bot.run(os.environ["DISCORD_TOKEN"])
import OpenAI from "openai";
import { Client, Events, GatewayIntentBits } from "discord.js";
const llm = new OpenAI(); // reads OPENAI_BASE_URL and OPENAI_API_KEY
const bot = new Client({
intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent],
});
bot.on(Events.MessageCreate, async (msg) => {
if (msg.author.bot || !msg.mentions.has(bot.user)) return;
const reply = await llm.chat.completions.create({
model: "gpt-4o-mini",
messages: [{ role: "user", content: msg.cleanContent }],
});
await msg.reply(reply.choices[0].message.content.slice(0, 2000));
});
bot.login(process.env.DISCORD_TOKEN);
Use the asynchronous client (AsyncOpenAI) in discord.py: a synchronous call would hold up every other event while the
model answers. The same code calls Claude or Gemini: put a name such as claude-sonnet-4.5 in model. The gateway
translates the request and the answer back into the OpenAI shape.
For a slash command, reply with interaction.response.defer() first and send the answer with interaction.followup.send:
Discord gives an interaction only 3 seconds before it must be answered.
Streaming¶
A Discord message is posted whole, so most bots don't stream. If yours edits its message as the answer arrives, stream as in OpenAI SDK for Python; a stream from Claude or Gemini arrives as OpenAI chunks.
Tool calls¶
Tools work 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¶
raw = await 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¶
import openai
try:
reply = await llm.chat.completions.create(model="gpt-4o-mini", messages=messages)
except openai.APIStatusError as e:
code = e.response.headers.get("x-vidai-error-code")
text = ("That message was stopped by our guardrails." if code == "content_guardrail_blocked"
else "Something went wrong; try again in a minute.")
await msg.reply(text)
Match on x-vidai-error-code, not on the message. The full list 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. await llm.models.list()
returns exactly the models the bot's key may call.
What goes through the gateway¶
| In Discord | Through the gateway |
|---|---|
| Model calls your bot makes with an SDK pointed at the gateway | Yes, to every provider your organisation has set up |
| Discord's own features and other people's bots | No |
Check it works in a minute¶
Start the bot and mention it: "@yourbot reply with exactly: ok". It should answer ok. The call shows in Request
logs within seconds.
Good to know¶
- A message can hold at most 2,000 characters; cut or split longer answers, or set
max_tokens. - A bot in many servers can use one key per server, or per customer, so each one's spend is apart.
- The SDK retries twice by default; a fallback chain may already have tried another model first. 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.