Skip to content

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=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.