Bots

A bot is an account your own program runs: it welcomes people, answers commands, moderates, posts updates. It has a BOT tag next to its name, and your program talks to The Hub for it through the API.

Making a bot

Create it in the dashboard → Bots (or in The Hub: Settings → Bots). Copy the token it shows you: it's only shown once. New token makes another and switches the old one off.
Choose its permissions: what its invite link asks for, like Send messages or Kick members. People adding it can untick any of them.
Invite it. The dashboard makes an invite link: https://the-hub.coffee/app/?add_bot=<bot ID>&perms=<number>. Anyone who manages a space can open it and add your bot, if it's public. A private bot can only be added by you.
Run its program, on any computer or server you like.

When a bot joins with permissions, it gets a role of its own carrying them. Space admins can change that role like any other. A bot can belong to one of your apps, so people see who made it.

Talking to the API

Every request goes to https://the-hub.coffee/app/api.php?action=<name> with the token in a header:

Authorization: Bot vlb_…

(X-Bot-Token: vlb_… works too.) No cookies or CSRF token are needed. Send POST bodies as JSON with Content-Type: application/json. Every answer is JSON with "ok": true, or "ok": false and an "error".

Hearing new messages: `bot_events`

GET api.php?action=bot_events&after=<message id> returns up to 100 new messages, oldest first, from every channel and direct message the bot can see (never its own), and last_id to pass as after next time.

Call it once without after when your bot starts: it returns no messages and the current last_id, so the bot doesn't answer things said before it was running. Then ask every second or two.

Each message has id, channel_id, server_id (null in a direct message), channel_type (text or dm), channel_name, author (id, username, display_name, bot, …), content, attachments, reply, reactions, created_at and edited_at. Moderation replies have system: true.

A tiny bot

// Node 18+: answers "!ping" with "pong"
const API = 'https://the-hub.coffee/app/api.php?action=';
const headers = { Authorization: 'Bot ' + process.env.HUB_BOT_TOKEN, 'Content-Type': 'application/json' };
const call = (action, body) => fetch(API + action, body ? { method: 'POST', headers, body: JSON.stringify(body) } : { headers }).then(r => r.json());

let { last_id } = await call('bot_events');
setInterval(async () => {
    const r = await call('bot_events&after=' + last_id);
    last_id = r.last_id;
    for (const m of r.messages) {
        if (m.content === '!ping') await call('message_send', { channel_id: m.channel_id, content: 'pong', reply_to: m.id });
    }
}, 1500);

Limits

A bot can send 5 messages every 5 seconds; more get a 429 answer, so wait a moment and try again.

Keeping the token safe

Anyone with the token can act as the bot. Keep it out of code you share (read it from an environment variable), and make a new one if it leaks. Deleting a bot takes it out of every space and switches its token off; its messages stay, shown as "Deleted bot".

Bots

Making a bot#

Talking to the API#

Hearing new messages: bot_events#

A tiny bot#

Limits#