Bots & command sync

The one thing to understand first

A Velora bot is not a second account that a creator logs into and shares a password with. It is a bot identity owned by their existing account, which they authorize into a channel with a specific permission set they can revoke at any time — and which multiple apps can connect to at once.

That last part matters most for integrators. A creator running your tool alongside two others does not end up with three bots in their chat. They have one bot, and each app publishes its own commands into it. Velora tracks which app owns which command, so nothing collides silently and disconnecting one app never disturbs another.

The four moving parts

Connecting your app to a bot

All endpoints below are called with the user's OAuth token, so they run in your app's context automatically — you never pass your client_id in the body.

Show this list and let the creator choose. It includes their VBS bot and any bots created by other tools — picking an existing one is how they end up with a single shared bot rather than one per app.

Call this on startup. If it returns a connection, you are already set up and should not prompt the creator again.

{ "botId": "b3f1c2a4-..." }

{
  "botName":     "CoolBot",              // required, 3-30 chars, [a-zA-Z0-9_] only
  "description": "Does cool things",     // optional, max 500 chars
  "avatarUrl":   "https://..."           // optional; see avatar upload below
}

Returns 409 if the name is taken. Always check first with GET /api/integrations/oauth/bot/check-name/:botName.

Disconnecting removes your synced commands and restores any built-in commands your app had overridden. It does not delete the bot and does not affect other apps.

Command sync

Requires the bot:commands scope. This is a full replacementfor your app's commands on that bot: send the complete list every time. Triggers you omit are removed. Other apps' commands are untouched.

POST /api/integrations/oauth/bot/commands/sync
Authorization: Bearer <user access token>

{
  "botId": "b3f1c2a4-...",
  "commands": [
    {
      "trigger": "uptime",
      "description": "How long the stream has been live",
      "aliases": ["up"],
      "permissions": { "level": "everyone" },
      "cooldown": { "globalCooldown": 5, "userCooldown": 15 },
      "isPublic": true
    }
  ]
}

Field reference

Up to 500 commands per sync. Duplicate triggers inside a single payload are rejected with 400 — deduplicate before sending.

When your command collides with a built-in

If you sync a trigger that the bot already has as a Velora Bot Studio command, the built-in is deactivated and marked as overridden by your app— yours wins, and the creator's original definition is preserved rather than deleted.

When you later drop that trigger from your sync, or disconnect entirely, Velora restores the built-in automatically — but only if no other connected app is still syncing the same trigger. Nothing is silently lost, and no creator has to go re-enable anything by hand.

The response tells you exactly what happened:

{
  "success": true,
  "synced":    { "total": 12 },
  "overrides": {
    "vbsCommandsDisabled": 1,
    "vbsCommandsRestored": 0
  }
}

Surfacing vbsCommandsDisabled in your own UI is a kindness — it lets a creator see that your !uptime replaced theirs, instead of wondering why theirs stopped answering.

What a bot can actually do

The short version: read chat, talk in chat, moderate chat, and run commands gated by viewer role — plus react to everything happening on the channel through the Events API.

Moderating chat

Yes, a bot can moderate — and the way it gets that power is deliberately the same way a human does. There is no separate bot-permission system to learn: a bot is granted the moderator role in a channel, exactly like any other moderator, by the broadcaster.

Every moderation call is checked against that role at request time. The broadcaster always passes; anyone else must hold the moderator role in that specific channel. A bot with the role in one channel has no power in any other.

Both halves are required for moderation: your app needs the chat:moderate OAuth scope and the acting account needs the moderator role. A scope alone grants nothing — that is the point. A creator who authorizes your app has not thereby handed you their chat; they still have to make the bot a mod, and they can un-mod it the moment they want to, from the same place they manage every other moderator.

{
  "action":          "timeout",          // delete | timeout | ban | unban
  "targetUsername":  "someviewer",       // or targetUserId
  "durationSeconds": 600,                // timeout only; default 600
  "reason":          "spam",             // optional
  "messageId":       "..."               // delete only
}

403 if the acting account is not a moderator or the broadcaster · 400 on an unknown action, a missing target, or delete without messageId.

If a moderation call returns 403, do not retry it.The account simply is not a moderator there. Surface it to the creator as “make the bot a moderator in your channel” — that is a thing they can fix in ten seconds, and a retry loop will never fix it for them.

Gating a command by viewer role

Separately from moderation, every command carries its own permission level, enforced by Velora before the command runs. Set it in the permissions field when you sync (see Command sync above):

An unrecognised level is denied, not allowed — if you send a typo, the command stops working rather than opening up to everyone. Pair the level with cooldown for rate control; the two are independent.

Bot names

Bot names live in the same namespace as user accounts. A bot named CoolBot means no user can register CoolBot, and vice versa. This is deliberate: it guarantees that a name in chat always identifies exactly one entity.

{ "available": true, "botName": "coolbot" }

Check as the creator types, not just on submit. Hitting 409 after they picked an avatar and a description is a bad first experience with your integration.

Renaming is limited to once every 90 days

A bot that people recognise in chat should not be able to change identity on a whim, so bot renames are on a 90-day cooldown. Attempting a rename inside that window fails with a clear error rather than silently succeeding.

{
  "canChange":     false,
  "lastChangeAt":  "2026-01-01T10:30:00Z",
  "nextChangeAt":  "2026-04-01T10:30:00Z",
  "daysRemaining": 45
}

Bot avatars

multipart/form-data with a single file field. The caller must own the bot.

POST /api/integrations/oauth/bot/b3f1c2a4-.../avatar
Content-Type: multipart/form-data

file: <binary>

→ 200
{
  "success": true,
  "bot": {
    "id":          "b3f1c2a4-...",
    "username":    "coolbot",
    "displayName": "CoolBot",
    "avatarUrl":   "https://assets.velora.tv/bot-avatars/b3f1c2a4-.../a1b2.png"
  }
}

Each upload gets a fresh randomised filename, so the returned avatarUrl changes every time and is safe to cache indefinitely. Always store the URL you get back rather than constructing one.

You can also pass an avatarUrlwhen creating a bot if you already host the image. Uploading is preferred — it survives your CDN going away, and it keeps the bot looking right even if a creator later stops using your tool.

Where a bot appears to viewers

A bot is a visible identity on Velora, not an invisible API caller. Knowing where it shows up tells you what your synced metadata is actually for.

What stays in the creator's hands

Creators manage their own bot from their Velora dashboard: profile and avatar, built-in commands, timed messages, variables, event triggers and shoutout overrides. Your app does not need to reimplement any of that, and generally shouldn't.

The dividing line is simple. You own your commands; the creator owns the bot. They can rename it, re-avatar it, revoke it from a channel, or disconnect your app entirely — without asking you, and without breaking the other tools connected to it.

Being a good citizen in a shared bot