Build a Voxara bot

Everything you need to write a bot for Voxara: creating one in the portal, the JavaScript SDK, the raw WebSocket protocol for any other language, and webhooks for when you only need to post.

What a bot is

A bot is a Voxara account you drive with code. It signs in with a token instead of a password, joins spaces like a member, and then talks to the server through exactly the same API the Voxara app uses: JSON frames over a WebSocket. Anything a member can do in a space, a bot with the same roles can do too.

There are two ways to build one:

• A bot keeps a WebSocket open. It receives every message and event in its spaces and can act on them. This is what you want for commands, moderation, or anything that reads messages.
• A webhook is one HTTPS URL bound to one text channel. POST some JSON to it and a message appears. Nothing to keep running, no sign-in, no library. Perfect for notifications. See Webhooks.

Bots carry a BOT tag everywhere they appear, take up a member slot in a space, and are subject to the space's moderation like anyone else.

Quick start

About five minutes, start to first reply.

1. Create the bot

Open the Developer Portal and sign in with your normal Voxara account. Click Create a bot, give it a display name and a username, and copy the token it shows you. It is shown once; you can reset it from the same page whenever you need to.

2. Add it to a space

Open the bot in the portal and use Add to a space. You can add it to any space you manage (you own it, or you hold a role with a management permission). A bot only sees the spaces it has been added to.

3. Get the SDK

The SDK is a single file with one dependency. In an empty folder:

# any Node.js 18 or newer
npm init -y
npm install ws
curl -O https://voxaraspace.com/developers/sdk/voxara-bot.js

Or download voxara-bot.js and drop it next to your script.

4. Write it

Save this as bot.js:

const { Client } = require('./voxara-bot');
const client = new Client();

client.on('ready', () => {
  console.log(`Signed in as ${client.user.displayName}`);
});

client.on('messageCreate', async (message) => {
  if (message.author.bot) return;          // never answer a bot, yourself included
  if (message.content === '!ping') await message.reply('pong');
});

client.login(process.env.VOXARA_BOT_TOKEN);

5. Run it

VOXARA_BOT_TOKEN=paste_your_token_here node bot.js

Type !ping in any channel of a space the bot is in. It replies pong. That is a working bot; everything below is what else it can do.

Tokens and safety

• The token is the account. Anyone who has it can post, delete and moderate as your bot, in every space it is in.
• Keep it in an environment variable or a secrets store, never in source code, never in a public repository, never in a screenshot.
• If it leaks, open the portal and Reset token. The old one stops working the same second.
• Bot tokens do not expire. A bot that goes offline can reconnect with the same token, which is why the SDK reconnects on its own.
• You can own up to 25 bots. Deleting a bot removes it from every space and invalidates its token.

Concepts

The JavaScript SDK

One file, voxara-bot.js, depending only on the ws package. It is a thin, readable wrapper over the protocol: an EventEmitter with a request helper, a few classes, automatic reconnection. If it does not do something you need, the raw protocol is always reachable through client.request(op, data).

npm install ws
const { Client, Message, Channel, Embed } = require('./voxara-bot');

Client

const client = new Client({
  reconnect: true,             // retry with backoff when the socket drops
  rejectUnauthorized: false,   // true to insist on a valid certificate chain
});
await client.login(token);              // resolves when the bot is ready

Properties (after ready)

Methods

Events

Subscribe with client.on(name, handler). Handlers may be async; the SDK does not wait for them, so catch your own errors.

Message

What messageCreate, send() and fetchMessages() hand you.

Methods: reply(content, options?), edit(content), delete(), react(emoji), pin(), unpin().

Channel

Every channel the bot can see, keyed by id in client.channels. The raw channel fields (id, guildId, name, type, topic, categoryId, slowmode, parentChannelId, locked, archived) are on the object directly, plus send(content, options?), fetchMessages(options?) and startTyping().

const general = [...client.channels.values()]
  .find((c) => c.guildId === guildId && c.type === 'text' && c.name === 'general');
await general.send('Good morning.');

Embeds

A message can carry one rich embed: a card with a title, description, side colour, up to ten fields, an image, a thumbnail, an author line, a footer and a timestamp.

const { Embed } = require('./voxara-bot');

const embed = new Embed()
  .setTitle('Deploy finished')
  .setURL('https://ci.example.com/build/482')
  .setDescription('Build **482** passed on `main`.')
  .setColor('#35c96a')
  .addField('Branch', 'main', true)
  .addField('Duration', '48s', true)
  .setThumbnail('https://example.com/logo.png')
  .setFooter('GitHub Actions')
  .setTimestamp();

await client.send(channelId, { embed });               // embed only
await client.send(channelId, 'Done.', { embed });       // text and embed

Values over a limit are truncated, not rejected. A message with no text, no attachment and an embed with nothing in it fails with empty_message. Editing an embed is not supported yet: delete and post again.

What your bot says about itself

In the Developer Portal, give the bot a description and tick the scopes it uses (reads messages, posts, sends DMs, moderates, voice, sends data outside Voxara). They appear on the bot's profile card, so a space owner knows what they are adding. They are a promise, not a permission: what the bot can actually do is decided by the roles the space gives it.

Slash commands

Declare commands once and people get them as autocomplete after typing / in any space the bot is in. A use never becomes a message; it arrives at the bot as a command event, and the bot answers however it likes.

client.on('ready', () => client.setCommands([
  { name: 'roll', description: 'Roll some dice', options: [{ name: 'sides', type: 'integer', description: 'How many sides (default 6)' }] },
  { name: 'poll', description: 'Start a quick poll', options: [{ name: 'question', required: true }] },
]));

client.on('command', async (cmd) => {
  if (cmd.name === 'roll') {
    const sides = cmd.options.sides || 6;
    await cmd.reply(`${cmd.user.displayName} rolled a ${1 + Math.floor(Math.random() * sides)}`);
  }
});

Limits: 25 commands per bot, 10 options each, names 1 to 32 characters (letters, digits, -, _). If the bot is offline the person is told so and nothing is sent. Raw protocol: bot:commands to declare, command:invoke event to receive.

Direct messages

client.on('memberAdd', async ({ guildId, user }) => {
  if (user.bot) return;
  const guild = client.guilds.get(guildId);
  try {
    await client.dm(user.id, `Welcome to ${guild.name}, ${user.displayName}!`);
  } catch (err) {
    if (err.code !== 'cannot_dm') throw err;
    // their privacy settings say no: greet them in a channel instead
  }
});

Rules: a bot can DM someone only if they share a space with it and the person's DM privacy allows it. Otherwise dm() rejects with cannot_dm; treat that as a normal outcome, not a failure. People cannot start a DM with a bot. A DM is a channel like any other once open: its messages come through messageCreate with message.guild === null.

Moderation bots

Give the bot a role in the space with the permissions it needs (space settings, Roles). The server enforces the same rules it applies to people:

• The action needs the permission: manageMessages to delete others' messages, pin, and lock threads; kickMembers to kick and time out; banMembers to ban and unban; moveMembers to move or disconnect people in voice.
• The target's highest role must be below the bot's highest role. The space owner cannot be moderated by anyone. A refusal comes back as forbidden.

const BANNED = ['buy followers', 'free nitro'];

client.on('messageCreate', async (message) => {
  if (message.author.bot || !message.guild) return;
  const text = message.content.toLowerCase();
  if (!BANNED.some((w) => text.includes(w))) return;
  await message.delete();
  await client.timeout(message.guild.id, message.authorId, 600);  // ten minutes
  await message.channel.send(`${message.author.displayName}, that is not allowed here.`);
});

Voice: client.on('raw', ...) receives voice:state events ({ channelId, users }) whenever someone joins or leaves a voice channel, which is how a bot knows who is where before calling moveToVoice or kickFromVoice.

Attachments and media

Attachment and picture URLs in the API are paths like /media/attachment-....png. They are private: fetching one needs a token in the query string. Use the bot's media token, which can read media and nothing else:

for (const file of message.attachments) {
  const res = await fetch(client.mediaUrl(file.url));   // https://host/media/...?t=<mediaToken>
  const bytes = Buffer.from(await res.arrayBuffer());
}

Uploading is upload:attachment on the raw protocol: { name, type, data } with data base64, which returns an attachment object you pass in send()'s options.attachments. Up to 4 per message.

Errors and rate limits

Every rejected request is an Error with a .code and a human-readable .message. Branch on the code, show the message.

try {
  await message.reply('hi');
} catch (err) {
  switch (err.code) {
    case 'rate_limited': /* back off */ break;
    case 'slowmode':     /* the channel's slow mode applies to bots without manageMessages */ break;
    case 'forbidden':    /* missing permission or role rank */ break;
    default: console.error(err.code, err.message);
  }
}

Guides for using the app

Not building a bot? These cover the app itself: creating a space, channels, roles and permissions, invite links and posting GitHub events into a channel.

The protocol, for any language

The SDK is optional. A bot is any WebSocket client that speaks the same JSON the app does. Python, Go, Rust, a shell script with websocat: all fine.

Connect and sign in

1. Open a WebSocket to wss://voxaraspace.com. Send the header Origin: app://pulse, or no Origin at all. Any other Origin is refused.
2. Send { "id": 1, "op": "auth:bot", "data": { "token": "YOUR_TOKEN" } }.
3. The reply is the ready payload: { "id": 1, "ok": true, "data": { user, guilds, users, mediaToken, ... } }. user.id is the bot's own id. guilds[] holds every space with its channels[], roles[] and memberIds[]; users is a map of everyone in those spaces.
4. From now on the server pushes events, and you send requests whenever you like.

Frames

// request: you choose the id, any string or number, unique per request in flight
{ "id": 7, "op": "message:send", "data": { "channelId": "1788…", "content": "hello" } }

// reply: same id, exactly once
{ "id": 7, "ok": true,  "data": { "message": { … } } }
{ "id": 7, "ok": false, "error": { "code": "forbidden", "message": "You cannot send messages in this channel." } }

// event: pushed by the server, no id
{ "op": "message:new", "data": { "message": { … } } }

Send { "op": "ping" } if you want a heartbeat; it is the one op that does not count toward the per-connection frame ceiling. Idle sockets are fine either way.

Operations a bot uses

Permissions on these are the same as for the SDK methods above. Ops the app uses for accounts, friends, billing and space administration exist too but are outside what a bot needs; the server refuses what a bot cannot do.

Server events

Object shapes

user

{ "id", "username", "displayName", "bot", "status", "customStatus", "bio",
  "avatarColor", "avatarUrl", "bannerUrl", "badges", "steamLinked", … }

message

{ "id", "channelId", "authorId", "content", "createdAt", "editedAt",
  "attachments": [{ "url", "name", "size", "type" }],
  "embeds": [{ "kind": "rich" | "link" | "steamgame", … }],
  "reactions": { "👍": ["userId"] },
  "mentions": ["userId"], "everyone": false,
  "replyTo": "messageId" | null, "threadId": null, "pinnedAt": null,
  "poll"?: { … }, "forwardedFrom"?: { … } }

guild (a space)

{ "id", "name", "description", "ownerId", "iconUrl", "iconColor",
  "channels": [{ "id", "name", "type", "topic", "categoryId", "slowmode" }],
  "categories": [{ "id", "name" }],
  "roles": [{ "id", "name", "color", "position", "permissions": { "manageMessages": true, … } }],
  "memberIds": ["userId"], "memberRoles": { "userId": ["roleId"] },
  "timeouts": { "userId": untilMs }, "emojis": [{ "name", "url" }] }

Python example

The same ping bot with the websockets package (pip install websockets), no SDK:

import asyncio, json, os, itertools
import websockets

SERVER = "wss://voxaraspace.com"
TOKEN = os.environ["VOXARA_BOT_TOKEN"]
ids = itertools.count(1)

async def main():
    async with websockets.connect(SERVER, origin="app://pulse") as ws:
        await ws.send(json.dumps({"id": next(ids), "op": "auth:bot", "data": {"token": TOKEN}}))
        ready = json.loads(await ws.recv())
        assert ready["ok"], ready
        me = ready["data"]["user"]["id"]
        print("signed in as", ready["data"]["user"]["displayName"])

        async for raw in ws:
            frame = json.loads(raw)
            if frame.get("op") != "message:new":
                continue
            m = frame["data"]["message"]
            if m["authorId"] == me or m["content"] != "!ping":
                continue
            await ws.send(json.dumps({"id": next(ids), "op": "message:send",
                "data": {"channelId": m["channelId"], "content": "pong", "replyTo": m["id"]}}))

asyncio.run(main())

A real bot would match replies to requests by id instead of ignoring them, reconnect when the socket closes, and send a WebSocket ping every 45 seconds or so to keep a quiet connection open. The SDK source is a good reference for all three.

Webhooks

A webhook is one URL that posts into one text channel. No socket, no sign-in, no library. Use it for anything that only needs to announce: CI results, deploys, alerts, forms, cron jobs.

Create one

In the Voxara app, right-click a text channel and choose Webhooks (or Edit channel, then Webhooks). Create one, give it a name, and copy the URL. Like a bot token, the URL is shown once and can be reset. Anyone managing the channel can create up to 10.

https://voxaraspace.com/wh/<id>/<token>

Post to it

curl https://voxaraspace.com/wh/<id>/<token> \
  -H 'content-type: application/json' \
  -d '{"content": "Deploy finished: v1.40.1 is live."}'

// reply
{ "ok": true, "message": { "id": "1788…", "createdAt": 1788874382726 } }
{ "ok": false, "error": { "code": "rate_limited", "message": "Too many requests." } }

The body is JSON with content (Markdown, up to 4000 characters) and/or an embed in the same shape as above:

{
  "embed": {
    "title": "Build 482 passed",
    "url": "https://ci.example.com/build/482",
    "description": "main · 48s",
    "color": "#35c96a",
    "fields": [{ "name": "Author", "value": "sam", "inline": true }],
    "footer": { "text": "GitHub Actions" },
    "timestamp": 1788874382726
  }
}

From GitHub Actions

- name: Tell Voxara
  run: |
    curl -sS "$VOXARA_WEBHOOK" -H 'content-type: application/json' \
      -d "{\"content\": \"${{ github.repository }}: ${{ job.status }} on ${{ github.ref_name }}\"}"
  env:
    VOXARA_WEBHOOK: ${{ secrets.VOXARA_WEBHOOK }}

From Python

import requests
requests.post(WEBHOOK_URL, json={"content": "Backup finished, 2.1 GB."}, timeout=10)

Ready-made templates

Point a service's own webhook at the URL with a suffix and Voxara turns its payload into a card; nothing to configure on their side.

Events the template has no card for (pings, labels, comments) are accepted and ignored, so nothing spams the channel.

Rules

• Text channels only (not forums, threads or voice).
• Body up to 16 KB. 30 posts per minute per webhook, 60 per minute from one address.
• Messages appear with the webhook's name and picture and a BOT tag. A webhook cannot read anything back, and it does not appear in the space's member list.
• Resetting a webhook invalidates the old URL immediately. Deleting the channel deletes its webhooks.
• A wrong id or token answers 404, the same as an unknown page, so the URL cannot be probed.

Limits

Hitting a limit is never fatal: the request is refused with a clear code and the bot stays connected.

Good practice

• Ignore bots. if (message.author.bot) return; at the top of every message handler. Without it two bots can talk to each other forever, and yours can answer itself.
• Prefix commands (!ping, /roll) and match exactly, so ordinary conversation never triggers them.
• Handle rate_limited by pausing, not retrying in a tight loop.
• Reply in place. Use message.reply() so people see what the bot is answering.
• Least privilege. Give the bot's role only the permissions it uses. A greeting bot needs none.
• Log codes, not tokens. Never print the token, the media token, or full frames containing them.
• Keep it running with something that restarts it (systemd, pm2, a container). The SDK reconnects by itself; a crash still needs a supervisor.
• Re-fetch when it matters. The caches are for convenience. Membership and roles change under you.

Troubleshooting

Something missing here? The SDK source, voxara-bot.js, is 400 readable lines and shows every frame it sends. A complete example bot is at ping-bot.js, and the same thing without the SDK at raw-ping-bot.js.