Necro for developers: bots and webhooks
Everything you need to connect your own program to Necro: a bot that reads and writes in the servers it is added to, answers slash commands and shows cards and buttons, or a webhook that lets any tool post into one channel.
The addresses
- REST API:
https://api.necro.ir/api/bot/v1 - Events gateway (socket.io):
https://api.necro.ir, path/socket.io, namespace/bots - A channel webhook:
https://necro.ir/api/webhooks/{id}/{token} - Make and manage bots: web.necro.ir → Settings → My Bots
1What a bot can do
A Necro bot is a program of your own. You make it in the app, it gets a token, and someone who manages a server adds it there. In that server it is a member with a BOT mark and a role of its own, and your program can:
- read the messages of the channels its role can see, as they arrive and from history;
- send messages, with cards, buttons, select menus and files; edit and delete its own messages;
- delete other people's messages, give and take roles, and mention
@everyone, when it was given those permissions; - register slash commands that people pick by typing
/in a channel, and answer them in the channel or to that person alone; - hear when it is added to or removed from a server and when members join or leave.
A bot cannot see private chats, groups, calls or voice channels, who is online, anyone's phone number or email, the other servers a member is in, or any channel its role does not see. It can never be an administrator, manage the server, its channels or webhooks, kick, ban, change nicknames, make invites or join voice.
A bot
A program with a token. It hears events over the gateway and acts over the REST API: it reads, writes and answers commands and clicks. Use it for anything that talks back.
A webhook
An address that only posts into one channel. No program has to run and nothing is read: a build server, a monitor or GitHub sends a request and the message appears. Use it for notifications.
Field names, numbers and limits follow Discord's where that costs nothing, so moving code over is mostly a matter of addresses. A tool made for Discord's webhooks works by changing the address. The gateway, though, is socket.io, not Discord's own protocol: Discord's libraries (discord.js, discord.py) do not connect to Necro as they are.
2Quick start
- Open web.necro.ir, go to Settings → My Bots and press New bot: a name (up to 32 characters, never one that passes for Necro), a few lines about it, a picture, and whether it is public. You can have up to 10 bots.
- Copy the token. It is shown only this once. Keep it secret: whoever has it controls your bot. If it is lost or someone saw it, press New token.
- Press Add to a server, choose what the bot asks for, open the link, pick a server where you have Manage Server and press Add. The bot appears in the member list.
- Run a program like the one below, then write
!pingin a channel the bot can see. It answerspong.
JavaScript (Node.js 18 or newer)
// npm i socket.io-client // NECRO_BOT_TOKEN=<the token> node bot.js const { io } = require('socket.io-client'); const BASE = 'https://api.necro.ir'; const API = `${BASE}/api/bot/v1`; const AUTH = `Bot ${process.env.NECRO_BOT_TOKEN}`; // One REST call: the answer's JSON (null for 204); a refusal throws with .status and .code async function api(method, route, body) { const res = await fetch(`${API}${route}`, { method, headers: { Authorization: AUTH, ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}) }, ...(body !== undefined ? { body: JSON.stringify(body) } : {}), }); if (res.status === 204) return null; const data = await res.json().catch(() => null); if (res.ok) return data; const err = new Error((data && data.message) || `HTTP ${res.status}`); err.status = res.status; err.code = (data && data.code) || null; throw err; } const gateway = io(`${BASE}/bots`, { auth: { token: AUTH }, transports: ['websocket'] }); gateway.on('ready', ({ user, servers }) => { console.log(`online as ${user.name} in ${servers.length} server(s)`); }); gateway.on('messageCreate', async ({ message }) => { if (message.author.isBot) return; // never answer a bot: your own messages come back to you too if (message.content.trim() !== '!ping') return; try { await api('POST', `/channels/${message.channelId}/messages`, { content: 'pong', replyTo: message.id }); } catch (err) { console.error('could not answer:', err.code || err.message); // MISSING_PERMISSIONS, RATE_LIMITED … } }); gateway.on('connect_error', (err) => { console.error('gateway refused:', (err.data && err.data.code) || err.message); });
Python 3
# pip install requests "python-socketio[client]" # NECRO_BOT_TOKEN=<the token> python bot.py import os import requests import socketio BASE = 'https://api.necro.ir' API = BASE + '/api/bot/v1' AUTH = 'Bot ' + os.environ['NECRO_BOT_TOKEN'] http = requests.Session() http.headers['Authorization'] = AUTH def api(method, route, body=None): r = http.request(method, API + route, json=body, timeout=15) if r.status_code == 204: return None data = r.json() if r.content else {} if not r.ok: raise RuntimeError(f"{r.status_code} {data.get('code')}: {data.get('message')}") return data sio = socketio.Client() @sio.on('ready', namespace='/bots') def ready(data): print('online as', data['user']['name'], 'in', len(data['servers']), 'server(s)') @sio.on('messageCreate', namespace='/bots') def message_create(data): m = data['message'] if m['author']['isBot']: return # never answer a bot if m['content'].strip() == '!ping': api('POST', f"/channels/{m['channelId']}/messages", {'content': 'pong', 'replyTo': m['id']}) @sio.on('connect_error', namespace='/bots') def refused(data): print('gateway refused:', data) sio.connect(BASE, namespaces=['/bots'], auth={'token': AUTH}, transports=['websocket']) sio.wait()
Keep the token in an environment variable, never in the code. The token dialog in My Bots shows a short version of the same program, ready to copy.
3Authentication
Every REST request and the gateway connection carry the bot's token, with the word Bot in front:
Authorization: Bot 1850.Xc9pQ2wE7rT1yU8iO3aS6dF0gH4jK5lZ2xC7vB1nM9q
- A token is the bot's id, a dot, and 43 random characters (
A-Z a-z 0-9 - _). Necro keeps only a hash of it, so it is shown once: when the bot is made or when you take a New token. - A new token makes the old one stop working at once, and every gateway connection of the bot is closed (the disconnect reason is
io server disconnect). - The token opens the bot API and the
/botsnamespace, nothing else: never the app, its pages or its own socket. - It works only while the bot exists, Necro has not turned it off, and its owner's account is in good standing. No token, a wrong one or a deleted bot's:
401 UNAUTHORIZED. A bot turned off, or whose owner's account is not active:403 BOT_DISABLED. - The API answers only at
api.necro.ir. On Necro's other addresses (web.necro.ir,necro.ir) it answers404 WRONG_HOST.
curl -H "Authorization: Bot $NECRO_BOT_TOKEN" https://api.necro.ir/api/bot/v1/me
{
"id": 1850,
"username": "bot_1850",
"name": "Dice",
"avatarUrl": "https://necro.ir/uploads/avatars/dice.webp",
"isBot": true,
"description": "Rolls dice and runs small polls.",
"public": false
}Never put a token in a web page, a browser extension, an app people download, a public repository or a command line (other programs on the computer can read a command line). Run your program on a computer or server of your own and read the token from the environment. If you think someone saw it, take a new one in My Bots: the old one stops working at once.
4Adding to a server and permissions
The add link
https://web.necro.ir/bots/add?client_id=1850&permissions=1025
- My Bots → Add to a server makes this link: you choose with switches what the bot asks for.
- Whoever opens it picks a server where they have Manage Server, sees each asked permission as a switch and a line saying what the bot will read, then presses Add. A permission they do not have themselves is off and locked: nobody hands out a permission they lack.
- A private bot (the default) can be added only by its owner. A public bot can be added by anyone who has its link and manages a server.
- A public bot can also be shown in the bots directory (in Server Settings → Apps and in My Bots). Its owner turns that on in My Bots and picks what the directory's Add button asks for.
- The bot's owner is never shown to the people of a server.
The bot's own role
An added bot gets one role of its own, named after it, just above @everyone. What it holds is what the link asked
for, minus what the adder switched off, cut to the permissions below and to what the adder has. That role cannot be deleted, given to anyone
else or taken from the bot; a manager who edits it can only set the permissions below. It can be moved in the role order like any role:
that decides which roles a bot with Manage Roles may give. It goes with the bot when the bot leaves.
What a bot may hold
| Permission | Bit | Value | What it lets the bot do |
|---|---|---|---|
| View Channels | 1 << 0 | 1 | See the channels its role sees and read their messages. |
| Manage Roles | 1 << 2 | 4 | Give and take roles ranked below its own highest role. Never @everyone, never a bot's role, never a role that allows more than the bot may do. |
| Send Messages | 1 << 10 | 1024 | Write in a channel and answer commands publicly. |
| Manage Messages | 1 << 13 | 8192 | Delete other people's messages; post in an announcement channel. |
| Mention @everyone | 1 << 19 | 524288 | Mention @everyone, @here and roles that are not mentionable. |
permissions= in the link is the sum of the values (their bitwise OR). Read and write, the default, is
1 + 1024 = 1025; all five is 533509. Any other bit is dropped.
const P = { VIEW_CHANNELS: 1, MANAGE_ROLES: 4, SEND_MESSAGES: 1024, MANAGE_MESSAGES: 8192, MENTION_EVERYONE: 524288 };
const permissions = P.VIEW_CHANNELS | P.SEND_MESSAGES | P.MANAGE_MESSAGES; // 9217
const link = `https://web.necro.ir/bots/add?client_id=${botId}&permissions=${permissions}`;Whatever roles a manager hands it later, a bot is never an owner or an administrator and holds only these five permissions. A bot given an administrator's role still hears no private channel it was not let into.
What a bot reads
- The channels its role sees: every channel open to all members, and a private channel only when the server's managers let its role (or the bot itself) into it.
- Their messages: the text, the addresses of files and who wrote them (id, username, name, picture), and the channels' names and topics.
- The server's name, picture and member count, its roles, and its member list (id, username, name, picture, nickname, roles, join date), and who joins or leaves.
- Never: private chats, groups, calls, voice, presence, phone numbers, emails, members' other servers, or a channel it does not see.
In the API, a server's and a channel's permissions say what the bot may do there. A manager removes a bot in
Server Settings → Apps, or kicks or bans it like a member; the bot can leave by itself with
DELETE/servers/{serverId}.
5The REST API
Base address: https://api.necro.ir/api/bot/v1. Bodies are JSON (read as JSON whatever the Content-Type says, up to 64 KB);
a message with files is multipart/form-data (section 10). Ids are numbers and times are ISO 8601.
A server the bot is not in, a channel it does not see and a message of such a channel answer as unknown.
| Endpoint | What it does |
|---|---|
| The bot | |
GET/me | The bot: { id, username, name, avatarUrl, isBot, description, public } |
GET/gateway | Where events come from: { url, path: "/socket.io", namespace: "/bots" } |
| Servers | |
GET/servers?after=&limit= | Its servers, by id (100 a page, up to 200): { id, name, description, iconUrl, ownerId, memberCount, permissions } |
GET/servers/{serverId} | One server. |
DELETE/servers/{serverId} | The bot leaves the server → 204 |
GET/servers/{serverId}/channels | The channels it sees: { id, serverId, name, type, topic, categoryId, position, private, permissions } |
GET/servers/{serverId}/roles | { id, name, color, position, permissions, managed, mentionable, hoist, isDefault } |
| Members and roles | |
GET/servers/{serverId}/members?after=&limit= | Members by id (100 a page, up to 1000): { user, nickname, roles, joinedAt } |
GET/servers/{serverId}/members/{userId} | One member. |
PUT/servers/{serverId}/members/{userId}/roles/{roleId} | Give a role → 204. Needs Manage Roles; the role is ranked below the bot's own (it shows in the server's audit log as the bot's). |
DELETE/servers/{serverId}/members/{userId}/roles/{roleId} | Take a role → 204. The same rules. |
| Channels and messages | |
GET/channels/{channelId} | One channel it sees. |
GET/channels/{channelId}/messages?limit=&before=&after= | History, newest first (50, up to 100). |
GET/channels/{channelId}/messages/{messageId} | One message. |
POST/channels/{channelId}/messages | Send { content?, embeds?, components?, replyTo? } (or files: section 10) → the message. Needs Send Messages; an announcement channel also needs Manage Messages. A voice channel: 400 INVALID_CHANNEL. |
PATCH/channels/{channelId}/messages/{messageId} | Edit its own message { content?, embeds?, components? } → the message. |
DELETE/channels/{channelId}/messages/{messageId} | Its own message, or anyone's with Manage Messages → 204 |
| Slash commands (section 7) | |
GET/commands | Its global commands. |
PUT/commands | Replace the whole set → the new set. |
POST/commands | Add one, or replace the one with that name → 201 / 200 |
DELETE/commands/{commandId} | → 204 |
GET/servers/{serverId}/commands | The same four for one server: GET, PUT, POST, and DELETE …/commands/{commandId}. |
| Answering interactions (section 7) | |
POST/interactions/{id}/{token}/callback | The first answer { type, data } → 204 |
PATCH/interactions/{id}/{token}/original | The answer itself after a defer, or an edit of it. |
DELETE/interactions/{id}/{token}/original | → 204 |
POST/interactions/{id}/{token}/followups | Another message (up to 10 per interaction). |
Paths are relative to the base address. replyTo may also be sent as reply_to or Discord's message_reference.message_id; it names a message of the same channel.
A message
{
"id": 48211,
"channelId": 734,
"serverId": 63,
"type": "text",
"content": "pong",
"author": {
"id": 1850,
"username": "bot_1850",
"name": "Dice",
"avatarUrl": "https://necro.ir/uploads/avatars/dice.webp",
"isBot": true
},
"replyTo": 48210,
"attachments": [],
"embeds": [],
"components": [],
"edited": false,
"createdAt": "2026-11-14T18:02:11.000Z"
}attachments: the message's file, as[{ url, name, size, contentType }].embeds: its cards, with picture addresses on Necro (section 8);components: its buttons and select menus (section 9).- A webhook's message has
author.idandauthor.usernameset tonull, the webhook's name, and awebhookId. - A message
contentis up to 2000 characters. A bot's message counts as unread without a sound; its mentions work as a member's do: a person by name, a role or@everyoneonly as its permissions allow. Slowmode does not hold it.
Pages
Messages come newest first. before gives the ones older than a message, after the ones right after it,
and limit how many. Servers and members are sorted by id: pass the last id you got as after.
// The whole history of a channel, newest to oldest let before = null; for (;;) { const page = await api('GET', `/channels/${channelId}/messages?limit=100${before ? `&before=${before}` : ''}`); if (!page.length) break; for (const m of page) handle(m); before = page[page.length - 1].id; // the oldest on this page }
Errors
A refusal is JSON with an HTTP status, in English, for programs:
{ "message": "Send Messages is needed in this channel", "code": "MISSING_PERMISSIONS" }
Too many requests is 429 RATE_LIMITED with retryAfter (seconds, also as retry_after) and a
Retry-After header: wait that long and try again. Every code is in section 12.
6The events gateway
Events reach your program over socket.io (version 4 of its protocol): the address https://api.necro.ir, path
/socket.io, namespace /bots. Send the token as auth: { token: 'Bot <token>' }
(an Authorization header works too).
const gateway = io('https://api.necro.ir/bots', { auth: { token: `Bot ${process.env.NECRO_BOT_TOKEN}` }, transports: ['websocket'] });
gateway.on('disconnect', (reason) => {
// 'io server disconnect': Necro closed it (a new token, the bot turned off or deleted).
// socket.io does not reconnect after that by itself; after any other reason it reconnects on its own.
console.log('disconnected:', reason);
});- Events only. What happens goes over REST; nothing your program sends on the gateway is read, and a connection that keeps sending is closed.
- Two connections per bot at most, counted over all of Necro's servers. A third is refused with
TOO_MANY_CONNECTIONS. readycomes after every connection, a reconnect included. Events are not kept for a bot that is not connected: after a reconnect, read what you missed over REST (after=the last message you saw).- A server's events arrive in the order they happened. Your bot shows as online in the member list while a connection is open.
- A refused connection gives
connect_errorwitherr.data.code:UNAUTHORIZED,BOT_DISABLED,BOTS_DISABLED,WRONG_HOST,TOO_MANY_CONNECTIONS, orRATE_LIMITED(20 wrong tokens a minute from one address). The first five do not get better by trying again.
| Event | Payload | When |
|---|---|---|
ready | { v, user, servers: [{ id, name }] } | The connection is open. |
serverCreate | { server } | The bot was added to a server. |
serverDelete | { serverId, reason } | The bot is out of a server: removed, kicked, banned, left or deleted (the server). |
messageCreate | { message } | A new message in a channel the bot sees, its own included. |
messageUpdate | { message } | A message was edited. |
messageDelete | { id, channelId, serverId } | A message was deleted. |
memberJoin | { serverId, member } | Someone joined a server of the bot's. |
memberLeave | { serverId, user } | Someone is no longer in it. Never why: whether they left, were kicked or banned is not told to members, so not to bots either. |
interactionCreate | { id, token, type, … } | Someone ran one of its commands or clicked one of its buttons (section 7, section 9). |
{
"v": 1,
"user": { "id": 1850, "username": "bot_1850", "name": "Dice", "avatarUrl": null, "isBot": true, "description": "", "public": false },
"servers": [{ "id": 63, "name": "Night Owls" }]
}{
"server": {
"id": 63,
"name": "Night Owls",
"description": null,
"iconUrl": "https://necro.ir/uploads/avatars/night-owls.webp",
"ownerId": 412,
"memberCount": 58,
"permissions": 1025
}
}{
"serverId": 63,
"member": {
"user": { "id": 977, "username": "kian", "name": "Kian", "avatarUrl": null, "isBot": false },
"nickname": null,
"roles": [],
"joinedAt": "2026-11-14T18:20:03.000Z"
}
}{ "serverId": 63, "reason": "kicked" }
{ "id": 48211, "channelId": 734, "serverId": 63 }messageCreate and messageUpdate carry a message as the REST API gives it.
7Slash commands and interactions
People type / in a channel and pick a command from a list. The list shows the commands of the bots that are in the server
and can see that channel. A command with options opens a small form; a command with one text option also runs as /name the text.
Your bot hears interactionCreate and answers over REST.
Registering
- Global commands (
/commands) work in every server the bot is in. A server's commands (/servers/{serverId}/commands) win over a global one of the same name there. Up to 100 of each: 100 global and 100 per server. PUTreplaces the whole set: a name you keep keeps its command id, a name you leave out goes.POSTadds one, or replaces the one with that name (201new,200replaced).- Command writes: 30 per 10 minutes per bot; a
PUTcounts once.
| Field | Rules |
|---|---|
name | 1 to 32 characters: lowercase letters of any script (ping, تاس), digits, - and _. A capital is lowered; anything else is refused. |
description | One line, 1 to 100 characters. |
options | Up to 25, required ones first, names unique: { type, name, description, required?, choices?, minValue?, maxValue?, minLength?, maxLength? } |
type | string, integer, number, boolean, user, channel, role, or Discord's numbers (3, 4, 10, 5, 6, 7, 8). |
choices | Up to 25, for string, integer and number: { name, value }, a name of 1 to 100 characters (a text value too). |
minValue maxValue | For numbers. minLength / maxLength: for text, up to 2000. Discord's snake_case (min_value …) is read too. |
Not supported yet, and refused with the reason: subcommands and their groups, "mentionable" options (use user or role),
attachment options, and user or message context-menu commands. autocomplete: true is read and ignored. Discord's type: 1
for the command itself is accepted.
await api('PUT', '/commands', [
{ name: 'ping', description: 'Is the bot there?' },
{ name: 'roll', description: 'Roll a die', options: [
{ type: 'integer', name: 'sides', description: 'How many sides', minValue: 2, maxValue: 1000 },
] },
]);curl -X PUT https://api.necro.ir/api/bot/v1/servers/63/commands \
-H "Authorization: Bot $NECRO_BOT_TOKEN" -H "Content-Type: application/json" \
-d '[{"name":"poll","description":"Start a poll","options":[{"type":"string","name":"question","description":"What to ask","required":true,"maxLength":200}]}]'When someone runs one
Before your bot hears anything, Necro checks that the person may write in the channel, that your bot sees the channel and has a gateway
connection open (otherwise the person is told the bot is offline), and that every value is of its type and inside its limits: a
user is a member of the server, a channel is one the person sees, a role is one of the server's.
A person may run 8 commands per 10 seconds.
{
"id": "q3V9xKk2mT0bYp1a",
"token": "lAqt3E2cR8vN0pZ5wJ7yH1kD6sF9gB4mX2uC8eT0oQa",
"type": "command",
"applicationId": 1850,
"serverId": 63,
"channelId": 734,
"user": { "id": 412, "username": "sara", "name": "Sara", "avatarUrl": null, "isBot": false },
"member": { "nickname": null, "roles": [91, 95], "joinedAt": "2026-10-02T09:14:00.000Z" },
"data": {
"id": 77,
"name": "roll",
"serverId": null,
"options": [{ "name": "sides", "type": "integer", "value": 12 }],
"resolved": { "users": {}, "members": {}, "channels": {}, "roles": {} }
},
"locale": "en",
"createdAt": "2026-11-14T18:05:42.120Z"
}
An option's type is its name. A user, channel or role value is an id; its details are in
resolved under that id (a user and their member details, a channel's { id, name, type, serverId }, a role).
locale is the person's language, fa or en.
Answering
The first answer must come within 5 seconds: POST/interactions/{id}/{token}/callback
with your bot's token too. After that the interaction lives 15 minutes for the answer itself, edits and follow-ups.
Nobody answers in time: the person is told the bot did not answer, and a late answer is 404.
| Type | Answer |
|---|---|
4 | A message: data = { content?, embeds?, components?, flags? }. With flags: 64 (or ephemeral: true) only that person sees it, as a note that is not stored. Without it, it is a message in the channel with "name used /command" over it. |
5 | Defer: the person sees that the bot is thinking. Write the answer later with PATCH …/original. With flags: 64 the later answer is for that person alone. |
6 · 7 | For buttons and select menus only (section 9). |
- PATCH
…/original{ content?, embeds?, components? }: after a defer, the answer itself; after a message, an edit of it. It returns the message (an only-you answer returns{ id: null, ephemeral: true, content }). - DELETE
…/originalremoves it →204. - POST
…/followups{ content?, embeds?, flags? }: another message, up to 10 per interaction. - Refusals:
404 UNKNOWN_INTERACTION(unknown, another bot's, a wrong token, or past its time),400 INTERACTION_ANSWERED(a second first answer),400 INTERACTION_NOT_ANSWERED(an edit or a follow-up before the first answer),403 MISSING_PERMISSIONS(the bot no longer sees the channel),409 CONFLICT(two edits race to write a deferred answer: try again).
gateway.on('interactionCreate', async (it) => {
if (it.type !== 'command') return;
const reply = (data) => api('POST', `/interactions/${it.id}/${it.token}/callback`, data);
if (it.data.name === 'ping') {
await reply({ type: 4, data: { content: 'pong', flags: 64 } }); // only the person sees it
} else if (it.data.name === 'roll') {
const opt = it.data.options.find((o) => o.name === 'sides');
const sides = opt ? opt.value : 6;
await reply({ type: 4, data: { content: `🎲 ${1 + Math.floor(Math.random() * sides)} (1–${sides})` } });
} else if (it.data.name === 'report') {
await reply({ type: 5 }); // "thinking…": now there are 15 minutes
const text = await buildReport();
await api('PATCH', `/interactions/${it.id}/${it.token}/original`, { content: text });
}
});@sio.on('interactionCreate', namespace='/bots')
def interaction(it):
if it['type'] == 'command' and it['data']['name'] == 'ping':
api('POST', f"/interactions/{it['id']}/{it['token']}/callback",
{'type': 4, 'data': {'content': 'pong', 'flags': 64}})curl -X POST "https://api.necro.ir/api/bot/v1/interactions/$IT_ID/$IT_TOKEN/callback" \
-H "Authorization: Bot $NECRO_BOT_TOKEN" -H "Content-Type: application/json" \
-d '{"type":4,"data":{"content":"pong","flags":64}}'8Cards (embeds)
A message can carry up to 10 cards in embeds, with up to 6000 characters of text over all of them. Cards are taken on
POST and PATCH of a channel message, on every interaction answer (callback, original, follow-ups) and on webhook posts.
| Field | Limit | What it is |
|---|---|---|
title | 256 | The card's heading; a link when url is there. |
url | http / https | Where the title leads. |
description | 4096 | The body, with the formatting below. |
color | 0xRRGGBB | The card's edge: a number (Discord's) or "#rrggbb". |
author | name 256 | { name, url?, icon_url? }, a line above the title. |
fields | 25 | [{ name, value, inline? }]: name up to 256, value up to 1024. Inline fields sit side by side (three to a row on a wide screen). |
thumbnail | { url } | A small picture beside the text. |
image | { url } | A big picture under it. |
footer | text 2048 | { text, icon_url? }, the last line. |
timestamp | ISO 8601 | A time shown in the footer. |
Formatting inside a card
In description, field values and the footer: **bold**, *italic* or _italic_,
`code`, a fenced code block (three backticks), [text](https://…) links and bare https://… links.
A plain message's content keeps no formatting.
Pictures
- Card pictures (
author.icon_url,thumbnail,image,footer.icon_url) are fetched once by Necro's server when the message is sent and served from Necro. People who read the card never load anything from your host, and your host never sees their addresses. - Up to 8 pictures per message, http or https to a public address, up to 3 redirects, up to 4 MB each; a picture that cannot be fetched is left out. Like link previews they are a cache: an old card may lose its picture one day.
attachment://chart.pngnames a file sent with the same message (section 10).- A message with cards and no text of its own shows older apps a plain-text version of the cards; the API's
contentstays empty for it.
{
"content": "Build finished",
"embeds": [{
"title": "necro-web #812 passed",
"url": "https://ci.example.com/builds/812",
"description": "**3 jobs** in 4 min — `main` at `c9aac44`",
"color": "#40d490",
"author": { "name": "CI" },
"fields": [
{ "name": "Tests", "value": "1,240 passed", "inline": true },
{ "name": "Time", "value": "4 min 12 s", "inline": true }
],
"footer": { "text": "ci.example.com" },
"timestamp": "2026-11-14T18:30:00Z"
}]
}9Buttons and select menus
A bot's message, and an interaction's answers and edits, can carry components: up to 5 rows. A row is
{ "type": 1, "components": [ … ] } with up to 5 buttons or exactly one select menu. Webhooks and only-you notes have none.
| Component | Fields |
|---|---|
Button type: 2 | style, label (up to 80), emoji?, custom_id (up to 100), url?, disabled?. A label or an emoji is needed. emoji is { "name": "🎲" } or "🎲": one emoji (a server's own emojis are not taken yet). |
Style 1 · 2 · 3 · 4 | Primary (blue), secondary (grey), success (green), danger (red): a click sends an interaction with its custom_id. |
Style 5 | A link: has a url (http or https) and no custom_id; it opens the address and sends nothing. |
Select type: 3 | custom_id, options (1 to 25: { label, value, description?, emoji?, default? }, each text up to 100), placeholder? (up to 150), min_values? (0 to 25, default 1), max_values? (1 to 25, default 1, never more than the options), disabled?. A pick sends an interaction with values. |
Types 4 (text input) and 5 to 8 (user, role, mentionable and channel selects) are refused with the reason (INVALID_BODY).
The custom_ids of one message are unique.
A click
Anyone who sees the channel can click (no Send Messages needed) on a component that is not disabled, up to 12 times per 10 seconds.
Your bot hears interactionCreate with type: "component":
{
"id": "Zk1mR4tW8yB2nQ6p",
"token": "pQ7wE2rT9yU4iO1aS8dF3gH6jK0lZ5xC2vB7nM4qW1e",
"type": "component",
"applicationId": 1850,
"serverId": 63,
"channelId": 734,
"user": { "id": 412, "username": "sara", "name": "Sara", "avatarUrl": null, "isBot": false },
"member": { "nickname": null, "roles": [91], "joinedAt": "2026-10-02T09:14:00.000Z" },
"message": { "id": 48230, "channelId": 734, "content": "Votes: 2", "…": "the message the button is on, as the REST API gives it" },
"data": { "custom_id": "vote", "component_type": 2 },
"locale": "en",
"createdAt": "2026-11-14T18:40:09.002Z"
}
A select menu's click has "component_type": 3 and "values": [ … ]. Answer it like a command (5 seconds for the first
answer, then 15 minutes), with two more types:
- 6, deferred update: acknowledged, nothing is shown.
- 7, update:
data = { content?, embeds?, components? }replaces those parts of the message the component is on. - After 6 or 7,
PATCH …/originaledits that same message. Types 4 (a new message, orflags: 64for that person alone) and 5 work as for commands.
// A vote with buttons; a click edits the message it is on await api('POST', `/channels/${channelId}/messages`, { content: 'Votes: 0', components: [{ type: 1, components: [ { type: 2, style: 3, label: 'Vote', emoji: '👍', custom_id: 'vote' }, { type: 2, style: 4, label: 'Close', custom_id: 'close' }, { type: 2, style: 5, label: 'Rules', url: 'https://example.com/rules' }, ], }], }); const votes = new Map(); // message id → the people who voted gateway.on('interactionCreate', async (it) => { if (it.type !== 'component') return; const update = (data) => api('POST', `/interactions/${it.id}/${it.token}/callback`, { type: 7, data }); const voters = votes.get(it.message.id) || new Set(); if (it.data.custom_id === 'vote') { voters.add(it.user.id); votes.set(it.message.id, voters); await update({ content: `Votes: ${voters.size}` }); } else if (it.data.custom_id === 'close') { await update({ content: `Closed with ${voters.size} vote(s)`, components: [] }); } });
{
"type": 1,
"components": [{
"type": 3,
"custom_id": "colour",
"placeholder": "Pick a colour",
"options": [
{ "label": "Red", "value": "red", "emoji": "🟥" },
{ "label": "Green", "value": "green", "emoji": "🟩", "default": true },
{ "label": "Blue", "value": "blue", "emoji": "🟦" }
]
}]
}10Sending files
POST/channels/{channelId}/messages and an interaction's follow-up take
multipart/form-data: the JSON body in a field named payload_json, the files in files[0] to
files[3] (any field name works). Webhooks take no files.
- Up to 4 files, 8 MB each. Pictures are handled as members' are, within the app's pixel limits, and script file types are refused.
- Files count in the bot's own daily upload quota, as a member's do.
- The files go out as an album: one message per file, shown together. The text, cards and buttons are on the first one. The answer is that first message, with
messageIds: the ids of all of them. - A card's
attachment://namepoints at a file of the same request. - The REST API lists a message's file in
attachments:[{ url, name, contentType }].
curl -X POST https://api.necro.ir/api/bot/v1/channels/734/messages \
-H "Authorization: Bot $NECRO_BOT_TOKEN" \
-F 'payload_json={"content":"The weekly report","embeds":[{"title":"Week 46","image":{"url":"attachment://chart.png"}}]}' \
-F "files[0]=@chart.png" \
-F "files[1]=@data.csv"const fs = require('fs');
const form = new FormData();
form.append('payload_json', JSON.stringify({
content: 'The weekly report',
embeds: [{ title: 'Week 46', image: { url: 'attachment://chart.png' } }],
}));
form.append('files[0]', new Blob([fs.readFileSync('chart.png')], { type: 'image/png' }), 'chart.png');
form.append('files[1]', new Blob([fs.readFileSync('data.csv')], { type: 'text/csv' }), 'data.csv');
// No Content-Type header: fetch writes the multipart one itself
const res = await fetch(`${API}/channels/${channelId}/messages`, { method: 'POST', headers: { Authorization: AUTH }, body: form });11Webhooks and GitHub
A webhook is an address that posts into one text or announcement channel. There is no account and no session: the address is the secret. Whoever has it can post in that channel and nothing else; it cannot read the channel or list its members.
Making one
- In Channel settings → Webhooks → New Webhook: a name and a picture. You need the Manage Webhooks permission (the owner and administrators have it) and to see the channel. Up to 10 per channel; a voice channel has none.
- The address is shown once. New address makes a new one; the old one stops working at once.
- An address works only while the member who was given it may still manage webhooks in that channel. If they lose that permission, or leave, it answers like an unknown address and the list marks the webhook as stopped; any manager's New address turns it back on.
https://necro.ir/api/webhooks/{id}/{token} (the token is 43 characters)Posting
| Field | What it is |
|---|---|
content | The text, up to 2000 characters. |
username | A sender name for this message alone, up to 80 characters. A name that passes for Necro is ignored and the webhook's own name is used. |
embeds | Cards, as in section 8. |
avatar_url | Accepted and ignored, as is anything else: Necro fetches no picture for a webhook. |
content or embeds is required. The body is read as JSON whatever the Content-Type says (up to 256 KB); a form
with content=… or Discord's payload_json works too, but a webhook takes no files. The answer is
200 { "ok": true, "id": … }; with ?wait=true it is the message. A GET of the address gives
{ id, name, avatarUrl, channelId, serverId }. Any other method answers 405 METHOD_NOT_ALLOWED: renaming or deleting a
webhook is done in the app.
curl -X POST "$NECRO_WEBHOOK_URL?wait=true" \
-H "Content-Type: application/json" \
-d '{"username":"Uptime","content":"web.example.com is back up"}'{
"id": 48240,
"channelId": 734,
"serverId": 63,
"content": "web.example.com is back up",
"webhookId": 41,
"author": { "name": "Uptime", "avatarUrl": null, "isBot": true },
"createdAt": "2026-11-14T18:50:00.000Z"
}import os, requests
requests.post(os.environ['NECRO_WEBHOOK_URL'], json={'username': 'Backup', 'content': 'Nightly backup finished'}, timeout=10)- A webhook's message shows under its name and picture with a WEBHOOK mark. It counts as unread without a sound, never mentions anyone, is not held by slowmode, may post in an announcement channel, and can be deleted and reported like any message.
- Limits: 5 posts per 2 seconds per webhook, 30 a minute per channel, 30
GETs a minute per webhook, and 20 addresses that open nothing a minute from one client address. - Refusals (English):
400 INVALID_BODY,404 UNKNOWN_WEBHOOK(the same answer for a wrong id, a wrong token, a deleted or replaced address and a stopped one),405 METHOD_NOT_ALLOWED,429 RATE_LIMITED,503 WEBHOOKS_DISABLED.
GitHub
- Make a webhook in the channel and copy its address.
- In GitHub: the repository's Settings → Webhooks → Add webhook.
- Payload URL: the webhook's address followed by
/github. Content type:application/json(orapplication/x-www-form-urlencoded). Choose the events you want, then Add webhook.
https://necro.ir/api/webhooks/{id}/{token}/github| GitHub event | The card |
|---|---|
push | The branch, up to 5 commits with their first line and author, and the compare link. |
pull_request | Opened, closed, merged, reopened, ready for review. |
pull_request_review | Submitted. |
issues | Opened, closed, reopened. |
issue_comment | Created. |
release | Published. |
create · delete | A branch or a tag. |
fork · watch | A fork; a star. |
workflow_run | Completed. |
ping | Answers 200 and posts nothing. |
Any other event or action answers 204 and posts nothing. The body may be up to 2 MB. GitHub's secret is not checked: the
address is the secret, so keep it as you would a password. The webhook's limits apply.
12Limits and errors
| What | Limit |
|---|---|
| Bots | |
| Bots per account | 10 at once, 20 made in a day |
| A bot's name / about text | 32 / 400 characters |
| REST API | |
| Requests per bot | 50 per 10 seconds |
| Messages per bot and channel | 5 per 5 seconds |
| Command writes per bot | 30 per 10 minutes (a PUT counts once) |
| Wrong tokens from one client address | 20 a minute |
| A JSON body | 64 KB |
A message's content | 2000 characters |
| Pages | messages 50, up to 100 · members 100, up to 1000 · servers 100, up to 200 |
| Gateway | |
| Connections per bot | 2 |
| Wrong tokens from one client address | 20 a minute |
| Commands and interactions | |
| Commands | 100 global + 100 per server |
| Options / choices | 25 / 25 |
| A text option's value | 2000 characters |
| The first answer | 5 seconds |
| An interaction's life | 15 minutes |
| Follow-ups | 10 per interaction |
| A person's commands / clicks | 8 / 12 per 10 seconds |
| Cards, buttons, files | |
| Cards per message | 10, with 6000 characters of text in all |
| Card pictures | 8 per message, 4 MB each |
| Rows / buttons per row | 5 / 5 (or one select menu) |
| Select options | 25 |
| Files | 4 per message, 8 MB each |
| Webhooks | |
| Webhooks per channel | 10 |
| Posts | 5 per 2 seconds per webhook, 30 a minute per channel |
GET of an address | 30 a minute per webhook |
| Addresses that open nothing | 20 a minute per client address |
| A body / a GitHub body | 256 KB / 2 MB |
content / username | 2000 / 80 characters |
Error codes
| Code | HTTP | What it means |
|---|---|---|
INVALID_BODY | 400 | The body is not valid; message says what. |
INVALID_CHANNEL | 400 | A voice channel takes no messages. |
INTERACTION_ANSWERED | 400 | The interaction already has its first answer. |
INTERACTION_NOT_ANSWERED | 400 | An edit or follow-up before the first answer. |
UNAUTHORIZED | 401 | No token, a wrong one, or a deleted bot's. |
MISSING_PERMISSIONS | 403 | The bot may not do that there. |
BOT_DISABLED | 403 | Necro turned the bot off, or its owner's account is not active. |
UNKNOWN_SERVER UNKNOWN_CHANNEL UNKNOWN_MESSAGE UNKNOWN_MEMBER UNKNOWN_ROLE UNKNOWN_COMMAND UNKNOWN_INTERACTION UNKNOWN_ROUTE | 404 | Not there, or not the bot's to see. |
WRONG_HOST | 404 | The bot API answers only at api.necro.ir. |
UNKNOWN_WEBHOOK | 404 | A webhook address that opens nothing. |
METHOD_NOT_ALLOWED | 405 | A webhook address takes only GET and POST. |
CONFLICT | 409 | Two edits raced to write a deferred answer: try again. |
RATE_LIMITED | 429 | Too many requests: wait retryAfter seconds (also the Retry-After header). |
SERVER_ERROR | 500 | Our fault: try again a little later. |
BOTS_DISABLED · WEBHOOKS_DISABLED | 503 | Bots or webhooks are turned off on Necro for now. |
{ "message": "You are being rate limited.", "code": "RATE_LIMITED", "retryAfter": 1.4, "retry_after": 1.4 }
Gateway refusals use the same names in err.data.code: UNAUTHORIZED, BOT_DISABLED,
BOTS_DISABLED, WRONG_HOST, TOO_MANY_CONNECTIONS, RATE_LIMITED, SERVER_ERROR.
13Rules
A bot speaks for whoever made it. Its owner answers for what it does:
- A bot may not pass for Necro or its team (such names are refused), send messages nobody asked for, scam people or post links that steal passwords, collect members' information for anything other than its own job, or work around the limits (with several bots, tokens or connections).
- Never let a bot answer other bots: two bots answering each other never stop. Your own messages come back to you too.
- People can report a bot's messages and the bot itself; the report is about the bot's owner. Necro's team can delete the message.
- Necro can turn a bot off: its token and connections are refused at once, and its owner sees that, with the reason, in My Bots. When the owner's account is banned or deleted, every bot of theirs stops.
- A server's managers decide what a bot does there: they edit its role, choose which private channels it sees, and remove, kick or ban it.
- The token is the owner's responsibility. Whatever is done with it is done by the bot. If it leaks, take a new one at once.
- Deleting a bot in My Bots takes it out of every server and its token stops working; its messages stay under its name.
What Necro tells its members about bots and webhooks is in the privacy policy.