نکروتوسعه‌دهندگان

نکرو برای توسعه‌دهندگان: بات و وب‌هوک

آخرین به‌روزرسانی:

هر چه برای وصل کردن برنامه‌ی خودتان به نکرو لازم دارید: باتی که در سرورهایی که به آن‌ها اضافه شده می‌خواند و می‌نویسد، به دستورهای اسلش جواب می‌دهد و کارت و دکمه نشان می‌دهد، یا وب‌هوکی که به هر ابزاری اجازه می‌دهد در یک کانال پیام بگذارد.

نشانی‌ها

۱بات چه کارهایی می‌کند

بات نکرو برنامه‌ای از خود شماست. آن را در اپ می‌سازید، یک توکن می‌گیرد و کسی که سروری را مدیریت می‌کند آن را به سرورش اضافه می‌کند. بات در آن سرور عضوی است با نشان BOT و یک نقش مخصوص خودش، و برنامه‌ی شما می‌تواند:

بات نمی‌تواند گفتگوهای خصوصی، گروه‌ها، تماس‌ها و کانال‌های صوتی را ببیند؛ نمی‌داند چه کسی آنلاین است، به شماره‌ی موبایل و ایمیل هیچ‌کس دسترسی ندارد و سرورهای دیگر اعضا یا کانالی را که نقشش نمی‌بیند نمی‌بیند. هیچ‌وقت مدیر کل نمی‌شود و نمی‌تواند سرور، کانال‌ها یا وب‌هوک‌هایش را مدیریت کند، کسی را بیرون یا بن کند، نام مستعار عوض کند، لینک دعوت بسازد یا وارد ویس شود.

بات

برنامه‌ای با توکن. رویدادها را از درگاه رویدادها می‌شنود و کارهایش را با REST API انجام می‌دهد: می‌خواند، می‌نویسد و به دستورها و کلیک‌ها جواب می‌دهد. برای هر چیزی که باید جواب بدهد.

وب‌هوک

نشانی‌ای که فقط در یک کانال پیام می‌گذارد. لازم نیست برنامه‌ای روشن بماند و چیزی خوانده نمی‌شود: سرور بیلد، ابزار مانیتورینگ یا گیت‌هاب یک درخواست می‌فرستد و پیام در کانال ظاهر می‌شود. برای اعلان‌ها.

نام فیلدها، عددها و محدودیت‌ها هر جا خرجی نداشته مثل دیسکورد است، پس آوردن کد از آنجا بیشتر عوض کردن نشانی‌هاست. ابزاری که برای وب‌هوک دیسکورد ساخته شده با عوض کردن نشانی کار می‌کند. اما درگاه رویدادهای نکرو socket.io است، نه پروتکل خود دیسکورد: کتابخانه‌های دیسکورد (discord.js، discord.py) همان‌طور که هستند به نکرو وصل نمی‌شوند.

۲شروع سریع

  1. web.necro.ir را باز کنید، به تنظیمات ← بات‌های من بروید و بات جدید را بزنید: یک نام (تا ۳۲ نویسه، و هیچ‌وقت نامی که خودش را جای نکرو جا بزند)، چند خط درباره‌اش، یک عکس، و اینکه عمومی باشد یا نه. تا ۱۰ بات می‌توانید داشته باشید.
  2. توکن را کپی کنید. فقط همین یک بار نشان داده می‌شود. آن را پیش خودتان نگه دارید: هر کس آن را داشته باشد بات شما را در دست دارد. اگر گم شد یا کسی آن را دید، توکن تازه را بزنید.
  3. افزودن به سرور را بزنید، انتخاب کنید بات چه دسترسی‌هایی بخواهد، لینک را باز کنید، سروری را که در آن «مدیریت سرور» دارید انتخاب کنید و بات را اضافه کنید. بات در فهرست اعضا پیدا می‌شود.
  4. برنامه‌ای مثل نمونه‌ی زیر را اجرا کنید و در کانالی که بات می‌بیند !ping بنویسید. بات جواب می‌دهد pong.

جاوااسکریپت (Node.js 18 یا جدیدتر)

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
# 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()

توکن را در یک متغیر محیطی نگه دارید، هیچ‌وقت در خود کد. پنجره‌ی توکن در «بات‌های من» نسخه‌ی کوتاهی از همین برنامه را آماده‌ی کپی نشان می‌دهد.

۳احراز هویت

هر درخواست REST و اتصال به درگاه رویدادها، توکن بات را با کلمه‌ی Bot پیش از آن می‌فرستد:

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
}

توکن را هیچ‌وقت در صفحه‌ی وب، افزونه‌ی مرورگر، اپی که مردم دانلود می‌کنند، مخزن عمومی یا خط فرمان نگذارید (برنامه‌های دیگرِ همان رایانه خط فرمان را می‌خوانند). برنامه‌تان را روی رایانه یا سرور خودتان اجرا کنید و توکن را از متغیر محیطی بخوانید. اگر فکر می‌کنید کسی آن را دیده، در «بات‌های من» توکن تازه بگیرید: توکن قبلی همان لحظه از کار می‌افتد.

۴افزودن به سرور و دسترسی‌ها

لینک افزودن

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

نقش مخصوص بات

باتی که اضافه می‌شود یک نقش مخصوص خودش می‌گیرد، هم‌نام خودش و درست بالای @everyone. آنچه این نقش دارد همان است که لینک خواسته، منهای آنچه افزاینده خاموش کرده، و محدود به دسترسی‌های جدول زیر و به آنچه خود افزاینده دارد. این نقش را نمی‌شود حذف کرد، به کس دیگری داد یا از بات گرفت؛ مدیری که آن را ویرایش می‌کند فقط دسترسی‌های جدول زیر را می‌تواند تنظیم کند. مثل هر نقشی می‌شود جایش را در ترتیب نقش‌ها عوض کرد: همین تعیین می‌کند باتی که «مدیریت نقش‌ها» دارد چه نقش‌هایی را می‌تواند بدهد. وقتی بات می‌رود، نقشش هم با او می‌رود.

دسترسی‌هایی که بات می‌تواند داشته باشد

دسترسیبیتمقداربا آن چه می‌کند
دیدن کانال‌ها1 << 01کانال‌هایی را که نقشش می‌بیند ببیند و پیام‌هایشان را بخواند.
مدیریت نقش‌ها1 << 24نقش‌هایی را که پایین‌تر از بالاترین نقش خودش هستند بدهد و بگیرد؛ هیچ‌وقت @everyone، نقش یک بات یا نقشی که بیشتر از اختیار خود بات اجازه می‌دهد.
فرستادن پیام1 << 101024در کانال بنویسد و به دستورها جواب عمومی بدهد.
مدیریت پیام‌ها1 << 138192پیام دیگران را حذف کند و در کانال اطلاع‌رسانی پیام بگذارد.
منشن @everyone1 << 19524288@everyone، @here و نقش‌هایی را که منشن‌پذیر نیستند منشن کند.

permissions= در لینک، جمع این مقدارها (یا همان OR بیتی آن‌ها) است. خواندن و نوشتن، که پیش‌فرض است، 1 + 1024 = 1025 است و هر پنج دسترسی با هم 533509. بیت‌های دیگر کنار گذاشته می‌شوند.

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}`;

هر نقشی هم که مدیری بعدها به بات بدهد، بات هیچ‌وقت صاحب سرور یا مدیر کل نمی‌شود و فقط همین پنج دسترسی را دارد. باتی که نقش مدیر کل گرفته باشد هم کانال خصوصی‌ای را که به آن راه داده نشده نمی‌شنود.

بات چه چیزهایی را می‌خواند

در API، فیلد permissions سرور و کانال می‌گوید بات آنجا چه کارهایی می‌تواند بکند. مدیر سرور بات را در تنظیمات سرور ← اپ‌ها برمی‌دارد یا مثل هر عضو دیگری بیرون یا بن می‌کند؛ بات هم می‌تواند خودش با DELETE/servers/{serverId} بیرون برود.

۵REST API

نشانی پایه: https://api.necro.ir/api/bot/v1. بدنه‌ها JSON هستند (با هر Content-Type که گفته شود، JSON خوانده می‌شوند، تا ۶۴ کیلوبایت)؛ پیام همراه فایل multipart/form-data است (بخش ۱۰). شناسه‌ها عدد هستند و زمان‌ها ISO 8601. سروری که بات عضوش نیست، کانالی که نمی‌بیند و پیامی از چنین کانالی، ناشناخته جواب داده می‌شوند.

مسیرکار
خود بات
GET/meخود بات: { id, username, name, avatarUrl, isBot, description, public }
GET/gatewayجایی که رویدادها از آن می‌آیند: { url, path: "/socket.io", namespace: "/bots" }
سرورها
GET/servers?after=&limit=سرورهای بات به ترتیب شناسه (۱۰۰ تا در هر صفحه، حداکثر ۲۰۰): { id, name, description, iconUrl, ownerId, memberCount, permissions }
GET/servers/{serverId}یک سرور.
DELETE/servers/{serverId}بات از سرور بیرون می‌رود؛ جواب: 204
GET/servers/{serverId}/channelsکانال‌هایی که می‌بیند: { id, serverId, name, type, topic, categoryId, position, private, permissions }
GET/servers/{serverId}/roles{ id, name, color, position, permissions, managed, mentionable, hoist, isDefault }
اعضا و نقش‌ها
GET/servers/{serverId}/members?after=&limit=اعضا به ترتیب شناسه (۱۰۰ تا در هر صفحه، حداکثر ۱۰۰۰): { user, nickname, roles, joinedAt }
GET/servers/{serverId}/members/{userId}یک عضو.
PUT/servers/{serverId}/members/{userId}/roles/{roleId}دادن نقش؛ جواب: 204. «مدیریت نقش‌ها» لازم است و نقش باید پایین‌تر از نقش خود بات باشد (در گزارش سرور به نام بات ثبت می‌شود).
DELETE/servers/{serverId}/members/{userId}/roles/{roleId}گرفتن نقش؛ جواب: 204. با همان قاعده‌ها.
کانال‌ها و پیام‌ها
GET/channels/{channelId}یکی از کانال‌هایی که می‌بیند.
GET/channels/{channelId}/messages?limit=&before=&after=تاریخچه، تازه‌ترین اول (۵۰ تا، حداکثر ۱۰۰)
GET/channels/{channelId}/messages/{messageId}یک پیام.
POST/channels/{channelId}/messagesفرستادن { content?, embeds?, components?, replyTo? } (یا فایل: بخش ۱۰)؛ جواب: خود پیام. «فرستادن پیام» لازم است و کانال اطلاع‌رسانی «مدیریت پیام‌ها» هم می‌خواهد. کانال صوتی: 400 INVALID_CHANNEL
PATCH/channels/{channelId}/messages/{messageId}ویرایش پیام خود بات { content?, embeds?, components? }؛ جواب: خود پیام.
DELETE/channels/{channelId}/messages/{messageId}پیام خود بات، یا پیام هر کسی با «مدیریت پیام‌ها»؛ جواب: 204
دستورهای اسلش (بخش ۷)
GET/commandsدستورهای سراسری بات.
PUT/commandsجایگزینی کل مجموعه؛ جواب: مجموعه‌ی تازه.
POST/commandsافزودن یک دستور یا جایگزینی دستوری با همان نام؛ جواب: 201 یا 200
DELETE/commands/{commandId}جواب: 204
GET/servers/{serverId}/commandsهمین چهار مسیر برای یک سرور: GET، PUT، POST و DELETE …/commands/{commandId}
جواب دادن به تعامل‌ها (بخش ۷)
POST/interactions/{id}/{token}/callbackجواب اول { type, data }؛ جواب: 204
PATCH/interactions/{id}/{token}/originalخود جواب بعد از تأخیر، یا ویرایش آن.
DELETE/interactions/{id}/{token}/originalجواب: 204
POST/interactions/{id}/{token}/followupsیک پیام دیگر (تا ۱۰ پیام برای هر تعامل)

مسیرها نسبت به نشانی پایه‌اند. replyTo را به شکل reply_to یا message_reference.message_id دیسکورد هم می‌شود فرستاد؛ پیامی از همان کانال را نشان می‌دهد.

یک پیام

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

صفحه‌بندی

پیام‌ها تازه‌ترین اول می‌آیند. before پیام‌های قدیمی‌تر از یک پیام را می‌دهد، after پیام‌های درست بعد از آن را، و limit تعدادشان را. سرورها و اعضا به ترتیب شناسه‌اند: آخرین شناسه‌ای را که گرفته‌اید به‌عنوان 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
}

خطاها

هر رد شدنی یک JSON با یک وضعیت HTTP است، به انگلیسی و برای برنامه‌ها:

JSON
{ "message": "Send Messages is needed in this channel", "code": "MISSING_PERMISSIONS" }

درخواستِ بیش از حد، 429 RATE_LIMITED می‌گیرد با retryAfter (به ثانیه، با نام retry_after هم) و سرآیند Retry-After: همان‌قدر صبر کنید و دوباره بفرستید. همه‌ی کدها در بخش ۱۲ آمده‌اند.

۶درگاه رویدادها

رویدادها با socket.io (نسخه‌ی ۴ پروتکلش) به برنامه‌ی شما می‌رسند: نشانی https://api.necro.ir، مسیر /socket.io و فضای نام /bots. توکن را به شکل auth: { token: 'Bot <token>' } بفرستید (سرآیند Authorization هم کار می‌کند).

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);
});
رویدادمحتواکی
ready{ v, user, servers: [{ id, name }] }اتصال باز شد.
serverCreate{ server }بات به سروری اضافه شد.
serverDelete{ serverId, reason }بات دیگر در سروری نیست: removed (برداشته شد)، kicked، banned، left یا deleted (خود سرور حذف شد).
messageCreate{ message }پیام تازه در کانالی که بات می‌بیند، پیام‌های خودش هم.
messageUpdate{ message }پیامی ویرایش شد.
messageDelete{ id, channelId, serverId }پیامی حذف شد.
memberJoin{ serverId, member }کسی به یکی از سرورهای بات پیوست.
memberLeave{ serverId, user }کسی دیگر در آن نیست. دلیلش هیچ‌وقت گفته نمی‌شود: اینکه رفته، بیرون شده یا بن شده به اعضا گفته نمی‌شود، پس به بات‌ها هم.
interactionCreate{ id, token, type, … }کسی یکی از دستورهای بات را اجرا کرد یا روی یکی از دکمه‌هایش زد (بخش ۷، بخش ۹).
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 و messageUpdate یک پیام دارند، به همان شکلی که REST API می‌دهد.

۷دستورهای اسلش و تعامل‌ها

اعضا در کانال / می‌زنند و از یک فهرست دستوری را انتخاب می‌کنند. فهرست، دستورهای بات‌هایی را نشان می‌دهد که عضو سرورند و آن کانال را می‌بینند. دستوری که گزینه دارد یک فرم کوچک باز می‌کند؛ دستوری که فقط یک گزینه‌ی متنی دارد به شکل /name the text هم اجرا می‌شود. بات شما interactionCreate را می‌شنود و با REST جواب می‌دهد.

ثبت دستورها

فیلدقاعده
name۱ تا ۳۲ نویسه: حروف کوچک از هر خطی (ping، تاس)، رقم، - و _. حرف بزرگ کوچک می‌شود و هر چیز دیگری رد می‌شود.
descriptionیک خط، از ۱ تا ۱۰۰ نویسه.
optionsتا ۲۵ گزینه، اول گزینه‌های اجباری، با نام‌های یکتا: { type, name, description, required?, choices?, minValue?, maxValue?, minLength?, maxLength? }
typestring، integer، number، boolean، user، channel، role، یا عددهای دیسکورد: 3, 4, 10, 5, 6, 7, 8
choicesتا ۲۵ انتخاب برای string، integer و number: { name, value }، با نامی از ۱ تا ۱۰۰ نویسه (مقدار متنی هم همین‌طور).
minValue maxValueبرای عددها. minLength و maxLength: برای متن، تا ۲۰۰۰ نویسه. شکل snake_case دیسکورد (min_value …) هم خوانده می‌شود.

این‌ها فعلاً پشتیبانی نمی‌شوند و با گفتن دلیل رد می‌شوند: زیردستورها و گروه‌هایشان، گزینه‌های mentionable (به جایش user یا role)، گزینه‌ی پیوست، و دستورهای منوی راست‌کلیک روی کاربر یا پیام. autocomplete: true خوانده و نادیده گرفته می‌شود. type: 1 دیسکورد برای خود دستور پذیرفته می‌شود.

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}]}]'

وقتی کسی دستوری را اجرا می‌کند

پیش از آنکه بات شما چیزی بشنود، نکرو بررسی می‌کند که آن شخص اجازه‌ی نوشتن در کانال را داشته باشد، بات شما کانال را ببیند و اتصالی باز به درگاه داشته باشد (وگرنه به شخص گفته می‌شود بات آفلاین است)، و هر مقدار از نوع خودش و در محدوده‌اش باشد: user عضو سرور باشد، channel کانالی که خود شخص می‌بیند و role یکی از نقش‌های سرور. هر شخص در هر ۱۰ ثانیه ۸ دستور می‌تواند اجرا کند.

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": "fa",
  "createdAt": "2026-11-14T18:05:42.120Z"
}

type هر گزینه نام نوعش است. مقدار user، channel یا role یک شناسه است و جزئیاتش زیر همان شناسه در resolved آمده (یک کاربر و جزئیات عضویتش، { id, name, type, serverId } یک کانال، یک نقش). locale زبان آن شخص است: fa یا en.

جواب دادن

جواب اول باید ظرف ۵ ثانیه برسد: POST/interactions/{id}/{token}/callback، این هم با توکن بات. بعد از آن تعامل ۱۵ دقیقه برای خود جواب، ویرایش‌ها و پیام‌های بعدی زنده می‌ماند. اگر کسی سر وقت جواب ندهد، به آن شخص گفته می‌شود بات جواب نداد و جواب دیرهنگام 404 می‌گیرد.

نوعجواب
4یک پیام: data = { content?, embeds?, components?, flags? }. با flags: 64 (یا ephemeral: true) فقط همان شخص آن را می‌بیند، به‌صورت یادداشتی که نگه داشته نمی‌شود. بدون آن، پیامی است در کانال که بالایش نوشته شده چه کسی از کدام دستور استفاده کرد.
5تأخیر: شخص می‌بیند که بات دارد فکر می‌کند. جواب را بعداً با PATCH …/original بنویسید. با flags: 64 جواب بعدی فقط برای همان شخص است.
6 · 7فقط برای دکمه‌ها و منوهای انتخاب (بخش ۹)
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}}'

۸کارت‌ها

هر پیام می‌تواند تا ۱۰ کارت در embeds داشته باشد، با روی هم حداکثر ۶۰۰۰ نویسه متن. کارت‌ها در POST و PATCH پیام کانال، در همه‌ی جواب‌های تعامل (callback، original و پیام‌های بعدی) و در پیام‌های وب‌هوک پذیرفته می‌شوند.

فیلدحدچیست
title۲۵۶عنوان کارت؛ اگر url باشد، لینک می‌شود.
urlhttp / httpsجایی که عنوان به آن می‌رود.
description۴۰۹۶متن اصلی، با قالب‌بندی‌ای که پایین‌تر آمده.
color0xRRGGBBلبه‌ی کارت: یک عدد (مثل دیسکورد) یا "#rrggbb".
authorنام ۲۵۶{ name, url?, icon_url? }، خطی بالای عنوان.
fields۲۵[{ name, value, inline? }]: نام تا ۲۵۶ و مقدار تا ۱۰۲۴ نویسه. فیلدهای inline کنار هم می‌نشینند (روی صفحه‌ی پهن، سه تا در هر ردیف).
thumbnail{ url }عکسی کوچک کنار متن.
image{ url }عکسی بزرگ زیر آن.
footerمتن ۲۰۴۸{ text, icon_url? }، خط آخر.
timestampISO 8601زمانی که در خط آخر نشان داده می‌شود.

قالب‌بندی داخل کارت

در description، مقدار فیلدها و خط آخر: **bold**، *italic* یا _italic_، `code`، بلوک کد میان سه بک‌تیک، لینک [text](https://…) و لینک ساده‌ی https://…. content پیام معمولی قالب‌بندی نمی‌گیرد.

عکس‌ها

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"
  }]
}

۹دکمه‌ها و منوهای انتخاب

پیام بات و جواب‌ها و ویرایش‌های یک تعامل می‌توانند components داشته باشند: تا ۵ ردیف. هر ردیف { "type": 1, "components": [ … ] } است، با حداکثر ۵ دکمه یا دقیقاً یک منوی انتخاب. پیام وب‌هوک و یادداشتی که فقط برای یک نفر است دکمه ندارند.

جزءفیلدها
دکمه type: 2style، label (تا ۸۰)، emoji?، custom_id (تا ۱۰۰)، url?، disabled?. برچسب یا ایموجی لازم است. emoji یا { "name": "🎲" } است یا "🎲": یک ایموجی (ایموجی‌های اختصاصی سرور فعلاً پذیرفته نمی‌شوند).
سبک 1 · 2 · 3 · 4اصلی (آبی)، فرعی (خاکستری)، موفقیت (سبز)، خطر (قرمز): کلیک، یک تعامل با custom_id همان دکمه می‌فرستد.
سبک 5لینک: یک url (با http یا https) دارد و custom_id ندارد؛ نشانی را باز می‌کند و چیزی نمی‌فرستد.
منوی انتخاب type: 3custom_id، options (۱ تا ۲۵ گزینه: { label, value, description?, emoji?, default? }، هر متن تا ۱۰۰ نویسه)، placeholder? (تا ۱۵۰)، min_values? (۰ تا ۲۵، پیش‌فرض ۱)، max_values? (۱ تا ۲۵، پیش‌فرض ۱، و هیچ‌وقت بیشتر از تعداد گزینه‌ها)، disabled?. انتخاب، یک تعامل با values می‌فرستد.

نوع ۴ (کادر متن) و نوع‌های ۵ تا ۸ (منوهای انتخاب کاربر، نقش، mentionable و کانال) با گفتن دلیل رد می‌شوند (INVALID_BODY). custom_idهای هر پیام یکتا هستند.

یک کلیک

هر کسی که کانال را می‌بیند می‌تواند روی جزئی که غیرفعال نیست کلیک کند («فرستادن پیام» لازم نیست)، تا ۱۲ بار در هر ۱۰ ثانیه. بات شما interactionCreate را با 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": "fa",
  "createdAt": "2026-11-14T18:40:09.002Z"
}

کلیکِ منوی انتخاب "component_type": 3 و "values": [ … ] دارد. مثل دستورها جوابش را بدهید (۵ ثانیه برای جواب اول، بعد ۱۵ دقیقه)، با دو نوع دیگر:

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": "🟦" }
    ]
  }]
}

۱۰فرستادن فایل

POST/channels/{channelId}/messages و پیام بعدی یک تعامل، multipart/form-data هم می‌پذیرند: بدنه‌ی JSON در فیلدی به نام payload_json و فایل‌ها در files[0] تا files[3] (هر نام فیلدی کار می‌کند). وب‌هوک فایل نمی‌پذیرد.

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 });

۱۱وب‌هوک‌ها و گیت‌هاب

وب‌هوک نشانی‌ای است که فقط در یک کانال متنی یا اطلاع‌رسانی پیام می‌گذارد. حساب و نشستی در کار نیست: خود نشانی رمز است. هر کس آن را داشته باشد می‌تواند در آن کانال پیام بگذارد و کار دیگری از دستش برنمی‌آید: نه کانال را می‌خواند و نه اعضایش را می‌بیند.

ساختن وب‌هوک

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

فرستادن پیام

فیلدچیست
contentمتن، تا ۲۰۰۰ نویسه.
usernameنام فرستنده فقط برای همین پیام، تا ۸۰ نویسه. نامی که خودش را جای نکرو جا بزند نادیده گرفته می‌شود و نام خود وب‌هوک می‌آید.
embedsکارت‌ها، مثل بخش ۸
avatar_urlپذیرفته و نادیده گرفته می‌شود، مثل هر فیلد دیگری: نکرو برای وب‌هوک هیچ عکسی دریافت نمی‌کند.

content یا embeds لازم است. بدنه با هر Content-Type که گفته شود JSON خوانده می‌شود (تا ۲۵۶ کیلوبایت)؛ فرم با content=… یا payload_json دیسکورد هم کار می‌کند، اما وب‌هوک فایل نمی‌پذیرد. جواب 200 { "ok": true, "id": … } است و با ?wait=true خود پیام. GET روی نشانی، { id, name, avatarUrl, channelId, serverId } را می‌دهد. هر روش دیگری 405 METHOD_NOT_ALLOWED می‌گیرد: تغییر نام یا حذف وب‌هوک در خود اپ انجام می‌شود.

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)

گیت‌هاب

  1. در کانال یک وب‌هوک بسازید و نشانی‌اش را کپی کنید.
  2. در گیت‌هاب، در تنظیمات مخزن: Settings → Webhooks → Add webhook
  3. Payload URL: نشانی وب‌هوک و پس از آن /github. Content type: application/json (یا application/x-www-form-urlencoded). رویدادهایی را که می‌خواهید انتخاب کنید و Add webhook را بزنید.
URL
https://necro.ir/api/webhooks/{id}/{token}/github
رویداد گیت‌هابکارت
pushشاخه، تا ۵ کامیت با خط اول و نویسنده‌ی هر کدام، و لینک مقایسه.
pull_requestباز شد، بسته شد، ادغام شد، دوباره باز شد، آماده‌ی بازبینی شد.
pull_request_reviewثبت شد.
issuesباز شد، بسته شد، دوباره باز شد.
issue_commentنوشته شد.
releaseمنتشر شد.
create · deleteیک شاخه یا یک برچسب.
fork · watchیک فورک؛ یک ستاره.
workflow_runتمام شد.
ping200 جواب می‌دهد و چیزی نمی‌فرستد.

هر رویداد یا کنش دیگری جواب 204 می‌گیرد و چیزی فرستاده نمی‌شود. بدنه تا ۲ مگابایت می‌تواند باشد. secret گیت‌هاب بررسی نمی‌شود: خود نشانی رمز است، پس مثل یک رمز عبور نگهش دارید. محدودیت‌های وب‌هوک اینجا هم هست.

۱۲محدودیت‌ها و خطاها

چه چیزیحد
بات‌ها
تعداد بات برای هر حساب۱۰ بات هم‌زمان، ۲۰ ساخت در روز
نام / توضیح بات۳۲ / ۴۰۰ نویسه
REST API
درخواست برای هر بات۵۰ در هر ۱۰ ثانیه
پیام برای هر بات در هر کانال۵ در هر ۵ ثانیه
نوشتن دستورها برای هر بات۳۰ در هر ۱۰ دقیقه (هر PUT یک بار)
توکن اشتباه از یک نشانی آی‌پی۲۰ در دقیقه
بدنه‌ی JSON۶۴ کیلوبایت
content پیام۲۰۰۰ نویسه
صفحه‌هاپیام‌ها ۵۰، حداکثر ۱۰۰؛ اعضا ۱۰۰، حداکثر ۱۰۰۰؛ سرورها ۱۰۰، حداکثر ۲۰۰
درگاه رویدادها
اتصال برای هر بات۲
توکن اشتباه از یک نشانی آی‌پی۲۰ در دقیقه
دستورها و تعامل‌ها
دستورها۱۰۰ سراسری + ۱۰۰ برای هر سرور
گزینه / انتخاب۲۵ / ۲۵
مقدار گزینه‌ی متنی۲۰۰۰ نویسه
جواب اول۵ ثانیه
عمر تعامل۱۵ دقیقه
پیام‌های بعدی۱۰ برای هر تعامل
دستور / کلیکِ هر شخص۸ / ۱۲ در هر ۱۰ ثانیه
کارت، دکمه، فایل
کارت در هر پیام۱۰، روی هم با ۶۰۰۰ نویسه متن
عکس کارت‌ها۸ در هر پیام، هر کدام ۴ مگابایت
ردیف / دکمه در هر ردیف۵ / ۵ (یا یک منوی انتخاب)
گزینه‌های منوی انتخاب۲۵
فایل۴ در هر پیام، هر کدام ۸ مگابایت
وب‌هوک‌ها
وب‌هوک در هر کانال۱۰
پیام۵ در هر ۲ ثانیه برای هر وب‌هوک، ۳۰ در دقیقه برای هر کانال
GET روی نشانی۳۰ در دقیقه برای هر وب‌هوک
نشانی‌های ناشناخته۲۰ در دقیقه از یک نشانی آی‌پی
بدنه / بدنه‌ی گیت‌هاب۲۵۶ کیلوبایت / ۲ مگابایت
content / username۲۰۰۰ / ۸۰ نویسه

کدهای خطا

کدHTTPمعنی
INVALID_BODY400بدنه معتبر نیست؛ message می‌گوید چرا.
INVALID_CHANNEL400کانال صوتی پیام نمی‌گیرد.
INTERACTION_ANSWERED400تعامل جواب اولش را گرفته است.
INTERACTION_NOT_ANSWERED400ویرایش یا پیام بعدی پیش از جواب اول.
UNAUTHORIZED401بدون توکن، توکن اشتباه یا توکن بات حذف‌شده.
MISSING_PERMISSIONS403بات اجازه‌ی این کار را آنجا ندارد.
BOT_DISABLED403نکرو بات را خاموش کرده یا حساب صاحبش فعال نیست.
UNKNOWN_SERVER UNKNOWN_CHANNEL UNKNOWN_MESSAGE UNKNOWN_MEMBER UNKNOWN_ROLE UNKNOWN_COMMAND UNKNOWN_INTERACTION UNKNOWN_ROUTE404وجود ندارد، یا بات اجازه‌ی دیدنش را ندارد.
WRONG_HOST404API بات فقط روی api.necro.ir جواب می‌دهد.
UNKNOWN_WEBHOOK404نشانی وب‌هوکی که چیزی را باز نمی‌کند.
METHOD_NOT_ALLOWED405نشانی وب‌هوک فقط GET و POST می‌پذیرد.
CONFLICT409دو ویرایش هم‌زمان برای نوشتن جواب تأخیری: دوباره بفرستید.
RATE_LIMITED429درخواست زیاد است: retryAfter ثانیه صبر کنید (سرآیند Retry-After هم همین را می‌گوید).
SERVER_ERROR500اشکال از ماست: کمی بعد دوباره امتحان کنید.
BOTS_DISABLED · WEBHOOKS_DISABLED503بات‌ها یا وب‌هوک‌ها فعلاً در نکرو خاموش‌اند.
JSON
{ "message": "You are being rate limited.", "code": "RATE_LIMITED", "retryAfter": 1.4, "retry_after": 1.4 }

ردهای درگاه رویدادها همین نام‌ها را در err.data.code دارند: UNAUTHORIZED، BOT_DISABLED، BOTS_DISABLED، WRONG_HOST، TOO_MANY_CONNECTIONS، RATE_LIMITED و SERVER_ERROR.

۱۳قوانین

بات از طرف سازنده‌اش حرف می‌زند و صاحبش پاسخگوی کارهای آن است:

آنچه نکرو درباره‌ی بات‌ها و وب‌هوک‌ها به اعضایش می‌گوید در سیاست حریم خصوصی آمده است.