NecroDevelopers

Necro for developers: bots and webhooks

Last updated:

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

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:

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

  1. 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.
  2. 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.
  3. 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.
  4. Run a program like the one below, then write !ping in a channel the bot can see. It answers pong.

JavaScript (Node.js 18 or newer)

JavaScript
// 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

Python
# 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:

HTTP
Authorization: Bot 1850.Xc9pQ2wE7rT1yU8iO3aS6dF0gH4jK5lZ2xC7vB1nM9q
curl
curl -H "Authorization: Bot $NECRO_BOT_TOKEN" https://api.necro.ir/api/bot/v1/me
JSON
{
  "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

URL
https://web.necro.ir/bots/add?client_id=1850&permissions=1025

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

PermissionBitValueWhat it lets the bot do
View Channels1 << 01See the channels its role sees and read their messages.
Manage Roles1 << 24Give 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 Messages1 << 101024Write in a channel and answer commands publicly.
Manage Messages1 << 138192Delete other people's messages; post in an announcement channel.
Mention @everyone1 << 19524288Mention @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.

JavaScript
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

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.

EndpointWhat it does
The bot
GET/meThe bot: { id, username, name, avatarUrl, isBot, description, public }
GET/gatewayWhere 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}/channelsThe 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}/messagesSend { 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/commandsIts global commands.
PUT/commandsReplace the whole set → the new set.
POST/commandsAdd one, or replace the one with that name → 201 / 200
DELETE/commands/{commandId}→ 204
GET/servers/{serverId}/commandsThe same four for one server: GET, PUT, POST, and DELETE …/commands/{commandId}.
Answering interactions (section 7)
POST/interactions/{id}/{token}/callbackThe first answer { type, data } → 204
PATCH/interactions/{id}/{token}/originalThe answer itself after a defer, or an edit of it.
DELETE/interactions/{id}/{token}/original→ 204
POST/interactions/{id}/{token}/followupsAnother 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

JSON
{
  "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"
}

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.

JavaScript
// 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:

JSON
{ "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).

JavaScript
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);
});
EventPayloadWhen
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).
ready
{
  "v": 1,
  "user": { "id": 1850, "username": "bot_1850", "name": "Dice", "avatarUrl": null, "isBot": true, "description": "", "public": false },
  "servers": [{ "id": 63, "name": "Night Owls" }]
}
serverCreate
{
  "server": {
    "id": 63,
    "name": "Night Owls",
    "description": null,
    "iconUrl": "https://necro.ir/uploads/avatars/night-owls.webp",
    "ownerId": 412,
    "memberCount": 58,
    "permissions": 1025
  }
}
memberJoin
{
  "serverId": 63,
  "member": {
    "user": { "id": 977, "username": "kian", "name": "Kian", "avatarUrl": null, "isBot": false },
    "nickname": null,
    "roles": [],
    "joinedAt": "2026-11-14T18:20:03.000Z"
  }
}
serverDelete · messageDelete
{ "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

FieldRules
name1 to 32 characters: lowercase letters of any script (ping, تاس), digits, - and _. A capital is lowered; anything else is refused.
descriptionOne line, 1 to 100 characters.
optionsUp to 25, required ones first, names unique: { type, name, description, required?, choices?, minValue?, maxValue?, minLength?, maxLength? }
typestring, integer, number, boolean, user, channel, role, or Discord's numbers (3, 4, 10, 5, 6, 7, 8).
choicesUp to 25, for string, integer and number: { name, value }, a name of 1 to 100 characters (a text value too).
minValue maxValueFor 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.

JavaScript
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
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.

interactionCreate
{
  "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.

TypeAnswer
4A 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.
5Defer: 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 · 7For buttons and select menus only (section 9).
JavaScript
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 });
  }
});
Python
@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
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.

FieldLimitWhat it is
title256The card's heading; a link when url is there.
urlhttp / httpsWhere the title leads.
description4096The body, with the formatting below.
color0xRRGGBBThe card's edge: a number (Discord's) or "#rrggbb".
authorname 256{ name, url?, icon_url? }, a line above the title.
fields25[{ 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.
footertext 2048{ text, icon_url? }, the last line.
timestampISO 8601A 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

JSON
{
  "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.

ComponentFields
Button type: 2style, 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 · 4Primary (blue), secondary (grey), success (green), danger (red): a click sends an interaction with its custom_id.
Style 5A link: has a url (http or https) and no custom_id; it opens the address and sends nothing.
Select type: 3custom_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":

interactionCreate
{
  "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:

JavaScript
// 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: [] });
  }
});
JSON
{
  "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.

curl
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"
JavaScript
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

URL
https://necro.ir/api/webhooks/{id}/{token}      (the token is 43 characters)

Posting

FieldWhat it is
contentThe text, up to 2000 characters.
usernameA 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.
embedsCards, as in section 8.
avatar_urlAccepted 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
curl -X POST "$NECRO_WEBHOOK_URL?wait=true" \
  -H "Content-Type: application/json" \
  -d '{"username":"Uptime","content":"web.example.com is back up"}'
JSON
{
  "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"
}
Python
import os, requests

requests.post(os.environ['NECRO_WEBHOOK_URL'], json={'username': 'Backup', 'content': 'Nightly backup finished'}, timeout=10)

GitHub

  1. Make a webhook in the channel and copy its address.
  2. In GitHub: the repository's Settings → Webhooks → Add webhook.
  3. Payload URL: the webhook's address followed by /github. Content type: application/json (or application/x-www-form-urlencoded). Choose the events you want, then Add webhook.
URL
https://necro.ir/api/webhooks/{id}/{token}/github
GitHub eventThe card
pushThe branch, up to 5 commits with their first line and author, and the compare link.
pull_requestOpened, closed, merged, reopened, ready for review.
pull_request_reviewSubmitted.
issuesOpened, closed, reopened.
issue_commentCreated.
releasePublished.
create · deleteA branch or a tag.
fork · watchA fork; a star.
workflow_runCompleted.
pingAnswers 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

WhatLimit
Bots
Bots per account10 at once, 20 made in a day
A bot's name / about text32 / 400 characters
REST API
Requests per bot50 per 10 seconds
Messages per bot and channel5 per 5 seconds
Command writes per bot30 per 10 minutes (a PUT counts once)
Wrong tokens from one client address20 a minute
A JSON body64 KB
A message's content2000 characters
Pagesmessages 50, up to 100 · members 100, up to 1000 · servers 100, up to 200
Gateway
Connections per bot2
Wrong tokens from one client address20 a minute
Commands and interactions
Commands100 global + 100 per server
Options / choices25 / 25
A text option's value2000 characters
The first answer5 seconds
An interaction's life15 minutes
Follow-ups10 per interaction
A person's commands / clicks8 / 12 per 10 seconds
Cards, buttons, files
Cards per message10, with 6000 characters of text in all
Card pictures8 per message, 4 MB each
Rows / buttons per row5 / 5 (or one select menu)
Select options25
Files4 per message, 8 MB each
Webhooks
Webhooks per channel10
Posts5 per 2 seconds per webhook, 30 a minute per channel
GET of an address30 a minute per webhook
Addresses that open nothing20 a minute per client address
A body / a GitHub body256 KB / 2 MB
content / username2000 / 80 characters

Error codes

CodeHTTPWhat it means
INVALID_BODY400The body is not valid; message says what.
INVALID_CHANNEL400A voice channel takes no messages.
INTERACTION_ANSWERED400The interaction already has its first answer.
INTERACTION_NOT_ANSWERED400An edit or follow-up before the first answer.
UNAUTHORIZED401No token, a wrong one, or a deleted bot's.
MISSING_PERMISSIONS403The bot may not do that there.
BOT_DISABLED403Necro 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_ROUTE404Not there, or not the bot's to see.
WRONG_HOST404The bot API answers only at api.necro.ir.
UNKNOWN_WEBHOOK404A webhook address that opens nothing.
METHOD_NOT_ALLOWED405A webhook address takes only GET and POST.
CONFLICT409Two edits raced to write a deferred answer: try again.
RATE_LIMITED429Too many requests: wait retryAfter seconds (also the Retry-After header).
SERVER_ERROR500Our fault: try again a little later.
BOTS_DISABLED · WEBHOOKS_DISABLED503Bots or webhooks are turned off on Necro for now.
JSON
{ "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:

What Necro tells its members about bots and webhooks is in the privacy policy.