Write a bot

Quick start

1. Create a botIn MODeep: Settings → Developer → Create bot. Copy the token right away: it is not shown again.
2. Add it to a serverCopy the install link and open it. Pick your server, review the permissions, Add. The bot joins with a role of its own.
3. First messageRun the curl or Node example below with your token. A ready-made example bot lives in apps/bots/example.

Authentication

Every request carries Authorization: Bot <token>. Base URL: https://api.modeep.net/bot/v1. A token is 32 random bytes; MODeep keeps only its hash and never logs it. If it leaks, Settings → Developer → Get a new token: the old token and its connections close at once. Bot accounts cannot sign in with a password or be added as friends. Answers are always { "ok": true, ... } or { "ok": false, "code": "..." }.

curl -X POST https://api.modeep.net/bot/v1/rooms/ROOM_ID/messages \
  -H "Authorization: Bot $MODEEP_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello MODeep!"}'

REST endpoints

GET /me

The bot itself and the servers it is in.

GET /servers

Servers it is installed in (with the permissions given in each).

GET /servers/:id

Rooms (only those it may read), categories, roles, member count. No emails or personal data.

GET /servers/:id/members

Members: name, picture, roles (needs members).

GET /rooms/:id/messages

Recent messages; ?before= pages back, ?limit= up to 60.

POST /rooms/:id/messages

{ text, replyTo?, card? }. A card: title, description, up to 8 fields, a role color.

PATCH / DELETE /messages/:id

Edits or deletes its own message (deleting others’ needs manageMessages).

PUT / DELETE /messages/:id/reactions/:emoji

Adds or removes a reaction.

POST /servers/:id/rooms, PATCH /rooms/:id

Creates a room, renames it or sets slow mode (manageRooms).

POST /servers/:id/members/:userId/kick | ban | mute

Kicks, bans or mutes ({ "muted": true }) a member ranked below the bot’s role.

GET / PUT /commands

The bot’s slash commands (PUT replaces the whole list).

POST /interactions/:id/reply

Answers a command: { text, card? }.

Gateway: events

Connect with socket.io to https://api.modeep.net/bot with auth: { token }. You get ready (the bot, its servers, the last event id), then only the events it may see: message.create, message.update, message.delete, reaction.add (rooms it can read), member.join, member.leave, voice.join, voice.leave (with members), command.invoke. Each event has a growing id: after a drop, reconnect with auth: { token, since: lastId } to get what you missed in the last 5 minutes. Bots never see direct messages between people, private (end-to-end encrypted) rooms or rooms they may not read.

import { io } from 'socket.io-client';

const token = process.env.MODEEP_BOT_TOKEN;
const api = (method, path, body) =>
  fetch('https://api.modeep.net/bot/v1' + path, {
    method,
    headers: { Authorization: 'Bot ' + token, 'Content-Type': 'application/json' },
    body: body && JSON.stringify(body),
  }).then((r) => r.json());

const socket = io('https://api.modeep.net/bot', { auth: { token } });
socket.on('ready', (r) => console.log('ready in', r.servers.length, 'servers'));
socket.on('message.create', async ({ roomId, data }) => {
  if (data.message.text === '!hello' && !data.message.author?.bot) {
    await api('POST', '/rooms/' + roomId + '/messages', { text: 'Hello!', replyTo: data.message.id });
  }
});

Slash commands

Register commands with PUT /commands: a name (lower case), a description, an optional English name and description, up to 5 options (string, int, user, room, bool). Everyone who may write in a room sees them under your bot’s name after typing “/”. When one is sent the bot gets command.invoke (interactionId, the options, who sent it); answer within 3 seconds with POST /interactions/:id/reply. If it takes longer the room shows “thinking…” and your answer replaces it. An answer is accepted for 15 minutes.

PUT /bot/v1/commands
{ "commands": [
  { "name": "zar", "description": "Zar atar", "nameEn": "dice", "descriptionEn": "Rolls a die",
    "options": [{ "name": "sides", "description": "How many sides", "type": "int", "required": false }] }
] }

Permissions

• readMessagesReads messages in the rooms it can access (events, history).
• sendMessagesSends messages, answers commands, adds reactions.
• commandsOffers slash commands.
• membersGets member and voice events and the member list.
• manageMessages, manageRoomsDeletes others’ messages, creates and edits rooms.
• kickMembers, banMembers, muteMembers, moveMembersOnly on members below its own role; never on the server owner.

Limits

• Requests30 a second per bot; more get 429 rate_limited.
• Messages5 a second in one room. Slow mode, auto-moderation and the message length (2000) apply to bots like everyone.
• BotsUp to 5 bots per account and 25 commands per bot.
• Event bufferThe last 5 minutes or 500 events; read older ones from history (GET /rooms/:id/messages).

Rules: bots follow the privacy policy and the community rules - no spam, no scraping, no unsolicited messages; keep what you read only as long as your bot needs it. A bot added to a server can read the messages of the rooms it was given access to; the bot’s developer is a separate data controller for that data. A bot that breaks the rules can be turned off everywhere by the MODeep team.