نکرو برای توسعهدهندگان: بات و وبهوک
هر چه برای وصل کردن برنامهی خودتان به نکرو لازم دارید: باتی که در سرورهایی که به آنها اضافه شده میخواند و مینویسد، به دستورهای اسلش جواب میدهد و کارت و دکمه نشان میدهد، یا وبهوکی که به هر ابزاری اجازه میدهد در یک کانال پیام بگذارد.
نشانیها
- REST API:
https://api.necro.ir/api/bot/v1 - درگاه رویدادها (socket.io):
https://api.necro.ir، مسیر/socket.io، فضای نام/bots - وبهوک کانال:
https://necro.ir/api/webhooks/{id}/{token} - ساخت و مدیریت باتها: web.necro.ir، در تنظیمات ← باتهای من
۱بات چه کارهایی میکند
بات نکرو برنامهای از خود شماست. آن را در اپ میسازید، یک توکن میگیرد و کسی که سروری را مدیریت میکند آن را به سرورش اضافه میکند. بات در آن سرور عضوی است با نشان BOT و یک نقش مخصوص خودش، و برنامهی شما میتواند:
- پیامهای کانالهایی را که نقشش میبیند بخواند، هم همان لحظه که میرسند و هم از تاریخچه؛
- پیام بفرستد، با کارت، دکمه، منوی انتخاب و فایل، و پیامهای خودش را ویرایش و حذف کند؛
- اگر این دسترسیها را به او داده باشند، پیام دیگران را حذف کند، نقش بدهد و بگیرد و
@everyoneرا منشن کند؛ - دستورهای اسلش ثبت کند که اعضا با زدن
/در کانال انتخابشان میکنند، و جوابشان را در کانال یا فقط برای همان شخص بدهد؛ - بفهمد کی به سروری اضافه یا از آن بیرون شده و کی اعضا میآیند یا میروند.
بات نمیتواند گفتگوهای خصوصی، گروهها، تماسها و کانالهای صوتی را ببیند؛ نمیداند چه کسی آنلاین است، به شمارهی موبایل و ایمیل هیچکس دسترسی ندارد و سرورهای دیگر اعضا یا کانالی را که نقشش نمیبیند نمیبیند. هیچوقت مدیر کل نمیشود و نمیتواند سرور، کانالها یا وبهوکهایش را مدیریت کند، کسی را بیرون یا بن کند، نام مستعار عوض کند، لینک دعوت بسازد یا وارد ویس شود.
بات
برنامهای با توکن. رویدادها را از درگاه رویدادها میشنود و کارهایش را با REST API انجام میدهد: میخواند، مینویسد و به دستورها و کلیکها جواب میدهد. برای هر چیزی که باید جواب بدهد.
وبهوک
نشانیای که فقط در یک کانال پیام میگذارد. لازم نیست برنامهای روشن بماند و چیزی خوانده نمیشود: سرور بیلد، ابزار مانیتورینگ یا گیتهاب یک درخواست میفرستد و پیام در کانال ظاهر میشود. برای اعلانها.
نام فیلدها، عددها و محدودیتها هر جا خرجی نداشته مثل دیسکورد است، پس آوردن کد از آنجا بیشتر عوض کردن نشانیهاست. ابزاری که برای وبهوک دیسکورد ساخته شده با عوض کردن نشانی کار میکند. اما درگاه رویدادهای نکرو socket.io است، نه پروتکل خود دیسکورد: کتابخانههای دیسکورد (discord.js، discord.py) همانطور که هستند به نکرو وصل نمیشوند.
۲شروع سریع
- web.necro.ir را باز کنید، به تنظیمات ← باتهای من بروید و بات جدید را بزنید: یک نام (تا ۳۲ نویسه، و هیچوقت نامی که خودش را جای نکرو جا بزند)، چند خط دربارهاش، یک عکس، و اینکه عمومی باشد یا نه. تا ۱۰ بات میتوانید داشته باشید.
- توکن را کپی کنید. فقط همین یک بار نشان داده میشود. آن را پیش خودتان نگه دارید: هر کس آن را داشته باشد بات شما را در دست دارد. اگر گم شد یا کسی آن را دید، توکن تازه را بزنید.
- افزودن به سرور را بزنید، انتخاب کنید بات چه دسترسیهایی بخواهد، لینک را باز کنید، سروری را که در آن «مدیریت سرور» دارید انتخاب کنید و بات را اضافه کنید. بات در فهرست اعضا پیدا میشود.
- برنامهای مثل نمونهی زیر را اجرا کنید و در کانالی که بات میبیند
!pingبنویسید. بات جواب میدهدpong.
جاوااسکریپت (Node.js 18 یا جدیدتر)
// 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); });
پایتون ۳
# 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 پیش از آن میفرستد:
Authorization: Bot 1850.Xc9pQ2wE7rT1yU8iO3aS6dF0gH4jK5lZ2xC7vB1nM9q
- توکن یعنی شناسهی بات، یک نقطه و ۴۳ نویسهی تصادفی (
A-Z a-z 0-9 - _). نکرو فقط هش آن را نگه میدارد، پس توکن فقط یک بار نشان داده میشود: وقتی بات ساخته میشود یا وقتی توکن تازه میگیرید. - توکن تازه، توکن قبلی را همان لحظه از کار میاندازد و همهی اتصالهای بات به درگاه بسته میشوند (دلیل قطع
io server disconnectاست). - توکن فقط API بات و فضای نام
/botsرا باز میکند و نه چیز دیگری: هیچوقت خود اپ، صفحههایش یا سوکت خودش را. - توکن تا وقتی کار میکند که بات حذف نشده باشد، نکرو آن را خاموش نکرده باشد و حساب صاحبش سالم باشد. بدون توکن، با توکن اشتباه یا توکن بات حذفشده:
401 UNAUTHORIZED. باتی که خاموش شده یا حساب صاحبش فعال نیست:403 BOT_DISABLED. - API فقط روی
api.necro.irجواب میدهد. روی نشانیهای دیگر نکرو (web.necro.ir،necro.ir) جوابش404 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
}توکن را هیچوقت در صفحهی وب، افزونهی مرورگر، اپی که مردم دانلود میکنند، مخزن عمومی یا خط فرمان نگذارید (برنامههای دیگرِ همان رایانه خط فرمان را میخوانند). برنامهتان را روی رایانه یا سرور خودتان اجرا کنید و توکن را از متغیر محیطی بخوانید. اگر فکر میکنید کسی آن را دیده، در «باتهای من» توکن تازه بگیرید: توکن قبلی همان لحظه از کار میافتد.
۴افزودن به سرور و دسترسیها
لینک افزودن
https://web.necro.ir/bots/add?client_id=1850&permissions=1025
- در «باتهای من»، دکمهی افزودن به سرور این لینک را میسازد: با کلیدها انتخاب میکنید بات چه بخواهد.
- کسی که لینک را باز میکند سروری را انتخاب میکند که در آن «مدیریت سرور» دارد، هر دسترسیِ خواستهشده را بهصورت یک کلید میبیند، همراه با خطی که میگوید بات چه چیزهایی را میخواند، و بعد بات را اضافه میکند. دسترسیای که خودش ندارد خاموش و قفل است: هیچکس دسترسیای را که ندارد به دیگری نمیدهد.
- بات خصوصی (حالت پیشفرض) را فقط صاحبش میتواند اضافه کند. بات عمومی را هر کسی که لینکش را داشته باشد و سروری را مدیریت کند.
- بات عمومی را میشود در فهرست باتها هم نشان داد («کشف باتها» در تنظیمات سرور ← اپها و در «باتهای من»). صاحبش در «باتهای من» گزینهی «نمایش در فهرست باتها» را روشن میکند و انتخاب میکند دکمهی افزودنِ فهرست چه دسترسیهایی بخواهد.
- صاحب بات هیچوقت به اعضای سرور نشان داده نمیشود.
نقش مخصوص بات
باتی که اضافه میشود یک نقش مخصوص خودش میگیرد، همنام خودش و درست بالای @everyone. آنچه این نقش دارد همان است
که لینک خواسته، منهای آنچه افزاینده خاموش کرده، و محدود به دسترسیهای جدول زیر و به آنچه خود افزاینده دارد. این نقش را نمیشود حذف کرد،
به کس دیگری داد یا از بات گرفت؛ مدیری که آن را ویرایش میکند فقط دسترسیهای جدول زیر را میتواند تنظیم کند. مثل هر نقشی میشود جایش را
در ترتیب نقشها عوض کرد: همین تعیین میکند باتی که «مدیریت نقشها» دارد چه نقشهایی را میتواند بدهد. وقتی بات میرود، نقشش هم با او میرود.
دسترسیهایی که بات میتواند داشته باشد
| دسترسی | بیت | مقدار | با آن چه میکند |
|---|---|---|---|
| دیدن کانالها | 1 << 0 | 1 | کانالهایی را که نقشش میبیند ببیند و پیامهایشان را بخواند. |
| مدیریت نقشها | 1 << 2 | 4 | نقشهایی را که پایینتر از بالاترین نقش خودش هستند بدهد و بگیرد؛ هیچوقت @everyone، نقش یک بات یا نقشی که بیشتر از اختیار خود بات اجازه میدهد. |
| فرستادن پیام | 1 << 10 | 1024 | در کانال بنویسد و به دستورها جواب عمومی بدهد. |
| مدیریت پیامها | 1 << 13 | 8192 | پیام دیگران را حذف کند و در کانال اطلاعرسانی پیام بگذارد. |
منشن @everyone | 1 << 19 | 524288 | @everyone، @here و نقشهایی را که منشنپذیر نیستند منشن کند. |
permissions= در لینک، جمع این مقدارها (یا همان OR بیتی آنها) است. خواندن و نوشتن، که پیشفرض است،
1 + 1024 = 1025 است و هر پنج دسترسی با هم 533509. بیتهای دیگر کنار گذاشته میشوند.
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 دیسکورد هم میشود فرستاد؛ پیامی از همان کانال را نشان میدهد.
یک پیام
{
"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: فایل پیام، به شکل[{ url, name, size, contentType }].embeds: کارتهای پیام، با نشانی عکسها روی نکرو (بخش ۸)؛components: دکمهها و منوهای انتخاب آن (بخش ۹).- در پیام وبهوک،
author.idوauthor.usernameبرابرnullاست، نام همان نام وبهوک است و فیلدwebhookIdهم دارد. contentپیام تا ۲۰۰۰ نویسه است. پیام بات بدون صدا خواندهنشده حساب میشود و منشنهایش مثل منشن یک عضوند: یک شخص با نامش، و یک نقش یا@everyoneفقط اگر دسترسیهایش اجازه بدهد. حالت آهسته جلویش را نمیگیرد.
صفحهبندی
پیامها تازهترین اول میآیند. before پیامهای قدیمیتر از یک پیام را میدهد، after پیامهای درست بعد از آن را،
و limit تعدادشان را. سرورها و اعضا به ترتیب شناسهاند: آخرین شناسهای را که گرفتهاید بهعنوان 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 }
خطاها
هر رد شدنی یک JSON با یک وضعیت HTTP است، به انگلیسی و برای برنامهها:
{ "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 هم کار میکند).
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);
});- فقط رویداد. کارها با REST انجام میشوند؛ هر چه برنامهتان روی درگاه بفرستد خوانده نمیشود و اتصالی که مدام بفرستد بسته میشود.
- حداکثر دو اتصال برای هر بات، روی همهی سرورهای نکرو با هم. اتصال سوم با
TOO_MANY_CONNECTIONSرد میشود. readyبعد از هر اتصال میآید، اتصال دوباره هم. رویدادها برای باتی که وصل نیست نگه داشته نمیشوند: بعد از اتصال دوباره، آنچه را از دست دادهاید با REST بخوانید (after=آخرین پیامی که دیدهاید).- رویدادهای هر سرور به همان ترتیبی میرسند که رخ دادهاند. تا وقتی اتصالی باز است، بات در فهرست اعضا آنلاین دیده میشود.
- اتصالی که رد شود
connect_errorمیدهد، باerr.data.code:UNAUTHORIZED،BOT_DISABLED،BOTS_DISABLED،WRONG_HOST،TOO_MANY_CONNECTIONSیاRATE_LIMITED(۲۰ توکن اشتباه در دقیقه از یک نشانی آیپی). پنج تای اول با دوباره امتحان کردن درست نمیشوند.
| رویداد | محتوا | کی |
|---|---|---|
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, … } | کسی یکی از دستورهای بات را اجرا کرد یا روی یکی از دکمههایش زد (بخش ۷، بخش ۹). |
{
"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 و messageUpdate یک پیام دارند، به همان شکلی که REST API میدهد.
۷دستورهای اسلش و تعاملها
اعضا در کانال / میزنند و از یک فهرست دستوری را انتخاب میکنند. فهرست، دستورهای باتهایی را نشان میدهد که عضو سرورند و
آن کانال را میبینند. دستوری که گزینه دارد یک فرم کوچک باز میکند؛ دستوری که فقط یک گزینهی متنی دارد به شکل /name the text
هم اجرا میشود. بات شما interactionCreate را میشنود و با REST جواب میدهد.
ثبت دستورها
- دستورهای سراسری (
/commands) در همهی سرورهایی که بات عضوشان است کار میکنند. دستورهای یک سرور (/servers/{serverId}/commands) آنجا بر دستور سراسریِ همنام مقدماند. از هر کدام تا ۱۰۰ دستور: ۱۰۰ سراسری و ۱۰۰ برای هر سرور. PUTکل مجموعه را جایگزین میکند: نامی که نگه میدارید شناسهی دستورش را هم نگه میدارد و نامی که نمیآورید حذف میشود.POSTیک دستور اضافه میکند یا دستوری با همان نام را جایگزین میکند (201برای تازه،200برای جایگزینشده).- نوشتن دستورها: ۳۰ بار در هر ۱۰ دقیقه برای هر بات؛ هر
PUTیک بار حساب میشود.
| فیلد | قاعده |
|---|---|
name | ۱ تا ۳۲ نویسه: حروف کوچک از هر خطی (ping، تاس)، رقم، - و _. حرف بزرگ کوچک میشود و هر چیز دیگری رد میشود. |
description | یک خط، از ۱ تا ۱۰۰ نویسه. |
options | تا ۲۵ گزینه، اول گزینههای اجباری، با نامهای یکتا: { type, name, description, required?, choices?, minValue?, maxValue?, minLength?, maxLength? } |
type | string، 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 دیسکورد برای خود دستور پذیرفته میشود.
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}]}]'وقتی کسی دستوری را اجرا میکند
پیش از آنکه بات شما چیزی بشنود، نکرو بررسی میکند که آن شخص اجازهی نوشتن در کانال را داشته باشد، بات شما کانال را ببیند و اتصالی باز به درگاه
داشته باشد (وگرنه به شخص گفته میشود بات آفلاین است)، و هر مقدار از نوع خودش و در محدودهاش باشد: user عضو سرور باشد،
channel کانالی که خود شخص میبیند و role یکی از نقشهای سرور. هر شخص در هر ۱۰ ثانیه ۸ دستور میتواند اجرا کند.
{
"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 | فقط برای دکمهها و منوهای انتخاب (بخش ۹) |
- PATCH
…/original{ content?, embeds?, components? }: بعد از تأخیر، خود جواب؛ بعد از پیام، ویرایش آن. خود پیام را برمیگرداند (جوابی که فقط برای آن شخص است{ id: null, ephemeral: true, content }برمیگرداند). - DELETE
…/originalآن را برمیدارد؛ جواب:204 - POST
…/followups{ content?, embeds?, flags? }: یک پیام دیگر، تا ۱۰ پیام برای هر تعامل. - ردها:
404 UNKNOWN_INTERACTION(ناشناخته، مال بات دیگر، توکن اشتباه یا گذشته از وقتش)،400 INTERACTION_ANSWERED(جواب اولِ دوباره)،400 INTERACTION_NOT_ANSWERED(ویرایش یا پیام بعدی پیش از جواب اول)،403 MISSING_PERMISSIONS(بات دیگر آن کانال را نمیبیند)،409 CONFLICT(دو ویرایش همزمان برای نوشتن جواب تأخیری: دوباره بفرستید).
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}}'۸کارتها
هر پیام میتواند تا ۱۰ کارت در embeds داشته باشد، با روی هم حداکثر ۶۰۰۰ نویسه متن. کارتها در POST و
PATCH پیام کانال، در همهی جوابهای تعامل (callback، original و پیامهای بعدی) و در پیامهای وبهوک پذیرفته میشوند.
| فیلد | حد | چیست |
|---|---|---|
title | ۲۵۶ | عنوان کارت؛ اگر url باشد، لینک میشود. |
url | http / https | جایی که عنوان به آن میرود. |
description | ۴۰۹۶ | متن اصلی، با قالببندیای که پایینتر آمده. |
color | 0xRRGGBB | لبهی کارت: یک عدد (مثل دیسکورد) یا "#rrggbb". |
author | نام ۲۵۶ | { name, url?, icon_url? }، خطی بالای عنوان. |
fields | ۲۵ | [{ name, value, inline? }]: نام تا ۲۵۶ و مقدار تا ۱۰۲۴ نویسه. فیلدهای inline کنار هم مینشینند (روی صفحهی پهن، سه تا در هر ردیف). |
thumbnail | { url } | عکسی کوچک کنار متن. |
image | { url } | عکسی بزرگ زیر آن. |
footer | متن ۲۰۴۸ | { text, icon_url? }، خط آخر. |
timestamp | ISO 8601 | زمانی که در خط آخر نشان داده میشود. |
قالببندی داخل کارت
در description، مقدار فیلدها و خط آخر: **bold**، *italic* یا _italic_،
`code`، بلوک کد میان سه بکتیک، لینک [text](https://…) و لینک سادهی https://….
content پیام معمولی قالببندی نمیگیرد.
عکسها
- عکسهای کارت (
author.icon_url،thumbnail،image،footer.icon_url) را سرور نکرو یک بار، وقتی پیام فرستاده میشود، دریافت میکند و از خود نکرو نشان میدهد. کسانی که کارت را میبینند هیچ چیزی از سرور شما بارگیری نمیکنند و سرور شما نشانی آنها را نمیبیند. - تا ۸ عکس برای هر پیام، با http یا https و به یک نشانی عمومی، حداکثر ۳ تغییر مسیر و تا ۴ مگابایت برای هر عکس؛ عکسی که دریافت نشود کنار گذاشته میشود. این عکسها مثل پیشنمایش لینکها نسخهی ذخیرهشدهاند: ممکن است کارت قدیمی روزی عکسش را از دست بدهد.
attachment://chart.pngبه فایلی اشاره میکند که با همان پیام فرستاده شده (بخش ۱۰).- پیامی که کارت دارد اما متنی از خودش ندارد، در اپهای قدیمیتر بهصورت نسخهی متنی سادهی کارتها دیده میشود؛
contentآن در API خالی میماند.
{
"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: 2 | style، label (تا ۸۰)، emoji?، custom_id (تا ۱۰۰)، url?، disabled?. برچسب یا ایموجی لازم است. emoji یا { "name": "🎲" } است یا "🎲": یک ایموجی (ایموجیهای اختصاصی سرور فعلاً پذیرفته نمیشوند). |
سبک 1 · 2 · 3 · 4 | اصلی (آبی)، فرعی (خاکستری)، موفقیت (سبز)، خطر (قرمز): کلیک، یک تعامل با custom_id همان دکمه میفرستد. |
سبک 5 | لینک: یک url (با http یا https) دارد و custom_id ندارد؛ نشانی را باز میکند و چیزی نمیفرستد. |
منوی انتخاب type: 3 | custom_id، options (۱ تا ۲۵ گزینه: { label, value, description?, emoji?, default? }، هر متن تا ۱۰۰ نویسه)، placeholder? (تا ۱۵۰)، min_values? (۰ تا ۲۵، پیشفرض ۱)، max_values? (۱ تا ۲۵، پیشفرض ۱، و هیچوقت بیشتر از تعداد گزینهها)، disabled?. انتخاب، یک تعامل با values میفرستد. |
نوع ۴ (کادر متن) و نوعهای ۵ تا ۸ (منوهای انتخاب کاربر، نقش، mentionable و کانال) با گفتن دلیل رد میشوند (INVALID_BODY).
custom_idهای هر پیام یکتا هستند.
یک کلیک
هر کسی که کانال را میبیند میتواند روی جزئی که غیرفعال نیست کلیک کند («فرستادن پیام» لازم نیست)، تا ۱۲ بار در هر ۱۰ ثانیه.
بات شما interactionCreate را با 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": "fa",
"createdAt": "2026-11-14T18:40:09.002Z"
}
کلیکِ منوی انتخاب "component_type": 3 و "values": [ … ] دارد. مثل دستورها جوابش را بدهید (۵ ثانیه برای جواب اول،
بعد ۱۵ دقیقه)، با دو نوع دیگر:
- ۶، بهروزرسانی تأخیری: دریافتش تأیید میشود و چیزی نشان داده نمیشود.
- ۷، بهروزرسانی:
data = { content?, embeds?, components? }همان بخشهای پیامی را که دکمه رویش است جایگزین میکند. - بعد از ۶ یا ۷،
PATCH …/originalهمان پیام را ویرایش میکند. نوع ۴ (پیامی تازه، یا باflags: 64فقط برای همان شخص) و نوع ۵ مثل دستورها کار میکنند.
// 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": "🟦" }
]
}]
}۱۰فرستادن فایل
POST/channels/{channelId}/messages و پیام بعدی یک تعامل،
multipart/form-data هم میپذیرند: بدنهی JSON در فیلدی به نام payload_json و فایلها در
files[0] تا files[3] (هر نام فیلدی کار میکند). وبهوک فایل نمیپذیرد.
- حداکثر ۴ فایل، هر کدام تا ۸ مگابایت. با عکسها همان کاری میشود که با عکسهای اعضا، در محدودهی پیکسلِ خود اپ، و فایلهای اسکریپت رد میشوند.
- فایلها در سهمیهی روزانهی آپلودِ خود بات حساب میشوند، مثل فایلهای اعضا.
- فایلها بهصورت آلبوم فرستاده میشوند: برای هر فایل یک پیام، که کنار هم نشان داده میشوند. متن، کارتها و دکمهها روی پیام اولاند. جواب همان پیام اول است، با
messageIds: شناسهی همهی آن پیامها. attachment://nameدر کارت به فایلی از همان درخواست اشاره میکند.- REST API فایل هر پیام را در
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 });۱۱وبهوکها و گیتهاب
وبهوک نشانیای است که فقط در یک کانال متنی یا اطلاعرسانی پیام میگذارد. حساب و نشستی در کار نیست: خود نشانی رمز است. هر کس آن را داشته باشد میتواند در آن کانال پیام بگذارد و کار دیگری از دستش برنمیآید: نه کانال را میخواند و نه اعضایش را میبیند.
ساختن وبهوک
- در تنظیمات کانال ← وبهوکها، وبهوک جدید را بزنید: یک نام و یک عکس. دسترسی «مدیریت وبهوکها» لازم است (صاحب سرور و مدیران کل آن را دارند) و باید کانال را ببینید. تا ۱۰ وبهوک برای هر کانال؛ کانال صوتی وبهوک ندارد.
- نشانی فقط یک بار نشان داده میشود. نشانی جدید نشانی تازهای میسازد و نشانی قبلی همان لحظه از کار میافتد.
- نشانی فقط تا وقتی کار میکند که عضوی که آن را گرفته هنوز اجازهی مدیریت وبهوکهای آن کانال را داشته باشد. اگر این اجازه را از دست بدهد یا برود، نشانی مثل یک نشانی ناشناخته جواب میدهد و فهرست، وبهوک را «از کار افتاده» نشان میدهد؛ «نشانی جدید»ِ هر مدیری دوباره راهش میاندازد.
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 -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)- پیام وبهوک با نام و عکس آن و نشان WEBHOOK نشان داده میشود. بدون صدا خواندهنشده حساب میشود، هیچوقت کسی را منشن نمیکند، حالت آهسته جلویش را نمیگیرد، میتواند در کانال اطلاعرسانی پیام بگذارد و مثل هر پیام دیگری حذف و گزارش میشود.
- محدودیتها: ۵ پیام در هر ۲ ثانیه برای هر وبهوک، ۳۰ پیام در دقیقه برای هر کانال، ۳۰
GETدر دقیقه برای هر وبهوک، و ۲۰ نشانیِ ناشناخته در دقیقه از یک نشانی آیپی. - ردها (به انگلیسی):
400 INVALID_BODY،404 UNKNOWN_WEBHOOK(یک جواب برای شناسهی اشتباه، توکن اشتباه، نشانی حذفشده یا عوضشده و نشانی از کار افتاده)،405 METHOD_NOT_ALLOWED،429 RATE_LIMITED،503 WEBHOOKS_DISABLED
گیتهاب
- در کانال یک وبهوک بسازید و نشانیاش را کپی کنید.
- در گیتهاب، در تنظیمات مخزن: Settings → Webhooks → Add webhook
- Payload URL: نشانی وبهوک و پس از آن
/github. Content type:application/json(یاapplication/x-www-form-urlencoded). رویدادهایی را که میخواهید انتخاب کنید و Add webhook را بزنید.
https://necro.ir/api/webhooks/{id}/{token}/github| رویداد گیتهاب | کارت |
|---|---|
push | شاخه، تا ۵ کامیت با خط اول و نویسندهی هر کدام، و لینک مقایسه. |
pull_request | باز شد، بسته شد، ادغام شد، دوباره باز شد، آمادهی بازبینی شد. |
pull_request_review | ثبت شد. |
issues | باز شد، بسته شد، دوباره باز شد. |
issue_comment | نوشته شد. |
release | منتشر شد. |
create · delete | یک شاخه یا یک برچسب. |
fork · watch | یک فورک؛ یک ستاره. |
workflow_run | تمام شد. |
ping | 200 جواب میدهد و چیزی نمیفرستد. |
هر رویداد یا کنش دیگری جواب 204 میگیرد و چیزی فرستاده نمیشود. بدنه تا ۲ مگابایت میتواند باشد. secret گیتهاب
بررسی نمیشود: خود نشانی رمز است، پس مثل یک رمز عبور نگهش دارید. محدودیتهای وبهوک اینجا هم هست.
۱۲محدودیتها و خطاها
| چه چیزی | حد |
|---|---|
| باتها | |
| تعداد بات برای هر حساب | ۱۰ بات همزمان، ۲۰ ساخت در روز |
| نام / توضیح بات | ۳۲ / ۴۰۰ نویسه |
| REST API | |
| درخواست برای هر بات | ۵۰ در هر ۱۰ ثانیه |
| پیام برای هر بات در هر کانال | ۵ در هر ۵ ثانیه |
| نوشتن دستورها برای هر بات | ۳۰ در هر ۱۰ دقیقه (هر PUT یک بار) |
| توکن اشتباه از یک نشانی آیپی | ۲۰ در دقیقه |
| بدنهی JSON | ۶۴ کیلوبایت |
content پیام | ۲۰۰۰ نویسه |
| صفحهها | پیامها ۵۰، حداکثر ۱۰۰؛ اعضا ۱۰۰، حداکثر ۱۰۰۰؛ سرورها ۱۰۰، حداکثر ۲۰۰ |
| درگاه رویدادها | |
| اتصال برای هر بات | ۲ |
| توکن اشتباه از یک نشانی آیپی | ۲۰ در دقیقه |
| دستورها و تعاملها | |
| دستورها | ۱۰۰ سراسری + ۱۰۰ برای هر سرور |
| گزینه / انتخاب | ۲۵ / ۲۵ |
| مقدار گزینهی متنی | ۲۰۰۰ نویسه |
| جواب اول | ۵ ثانیه |
| عمر تعامل | ۱۵ دقیقه |
| پیامهای بعدی | ۱۰ برای هر تعامل |
| دستور / کلیکِ هر شخص | ۸ / ۱۲ در هر ۱۰ ثانیه |
| کارت، دکمه، فایل | |
| کارت در هر پیام | ۱۰، روی هم با ۶۰۰۰ نویسه متن |
| عکس کارتها | ۸ در هر پیام، هر کدام ۴ مگابایت |
| ردیف / دکمه در هر ردیف | ۵ / ۵ (یا یک منوی انتخاب) |
| گزینههای منوی انتخاب | ۲۵ |
| فایل | ۴ در هر پیام، هر کدام ۸ مگابایت |
| وبهوکها | |
| وبهوک در هر کانال | ۱۰ |
| پیام | ۵ در هر ۲ ثانیه برای هر وبهوک، ۳۰ در دقیقه برای هر کانال |
GET روی نشانی | ۳۰ در دقیقه برای هر وبهوک |
| نشانیهای ناشناخته | ۲۰ در دقیقه از یک نشانی آیپی |
| بدنه / بدنهی گیتهاب | ۲۵۶ کیلوبایت / ۲ مگابایت |
content / username | ۲۰۰۰ / ۸۰ نویسه |
کدهای خطا
| کد | HTTP | معنی |
|---|---|---|
INVALID_BODY | 400 | بدنه معتبر نیست؛ message میگوید چرا. |
INVALID_CHANNEL | 400 | کانال صوتی پیام نمیگیرد. |
INTERACTION_ANSWERED | 400 | تعامل جواب اولش را گرفته است. |
INTERACTION_NOT_ANSWERED | 400 | ویرایش یا پیام بعدی پیش از جواب اول. |
UNAUTHORIZED | 401 | بدون توکن، توکن اشتباه یا توکن بات حذفشده. |
MISSING_PERMISSIONS | 403 | بات اجازهی این کار را آنجا ندارد. |
BOT_DISABLED | 403 | نکرو بات را خاموش کرده یا حساب صاحبش فعال نیست. |
UNKNOWN_SERVER UNKNOWN_CHANNEL UNKNOWN_MESSAGE UNKNOWN_MEMBER UNKNOWN_ROLE UNKNOWN_COMMAND UNKNOWN_INTERACTION UNKNOWN_ROUTE | 404 | وجود ندارد، یا بات اجازهی دیدنش را ندارد. |
WRONG_HOST | 404 | API بات فقط روی api.necro.ir جواب میدهد. |
UNKNOWN_WEBHOOK | 404 | نشانی وبهوکی که چیزی را باز نمیکند. |
METHOD_NOT_ALLOWED | 405 | نشانی وبهوک فقط GET و POST میپذیرد. |
CONFLICT | 409 | دو ویرایش همزمان برای نوشتن جواب تأخیری: دوباره بفرستید. |
RATE_LIMITED | 429 | درخواست زیاد است: retryAfter ثانیه صبر کنید (سرآیند Retry-After هم همین را میگوید). |
SERVER_ERROR | 500 | اشکال از ماست: کمی بعد دوباره امتحان کنید. |
BOTS_DISABLED · WEBHOOKS_DISABLED | 503 | باتها یا وبهوکها فعلاً در نکرو خاموشاند. |
{ "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.
۱۳قوانین
بات از طرف سازندهاش حرف میزند و صاحبش پاسخگوی کارهای آن است:
- بات نباید خودش را جای نکرو یا تیمش جا بزند (چنین نامهایی پذیرفته نمیشوند)، پیام ناخواسته بفرستد، کلاهبرداری کند یا لینکی بگذارد که رمز عبور میدزدد، اطلاعات اعضا را برای کاری جز کار خودش جمع کند، یا محدودیتها را دور بزند (با چند بات، چند توکن یا چند اتصال).
- هیچوقت نگذارید بات به باتهای دیگر جواب بدهد: دو باتی که به هم جواب میدهند هیچوقت متوقف نمیشوند. پیامهای خود بات هم به خودش برمیگردند.
- اعضا میتوانند پیامهای بات و خود بات را گزارش کنند؛ گزارش دربارهی صاحب بات است. تیم نکرو میتواند پیام را حذف کند.
- نکرو میتواند بات را خاموش کند: توکن و اتصالهایش همان لحظه رد میشوند و صاحبش این را، همراه با دلیلش، در «باتهای من» میبیند. اگر حساب صاحب بن یا حذف شود، همهی باتهایش از کار میافتند.
- مدیران سرور تعیین میکنند بات آنجا چه کند: نقشش را ویرایش میکنند، انتخاب میکنند کدام کانالهای خصوصی را ببیند، و آن را برمیدارند، بیرون میکنند یا بن میکنند.
- مسئولیت توکن با صاحب بات است. هر کاری با توکن انجام شود کار خود بات است. اگر لو رفت، همان لحظه توکن تازه بگیرید.
- حذف بات در «باتهای من» آن را از همهی سرورها بیرون میبرد و توکنش از کار میافتد؛ پیامهایش با نام خودش میمانند.
آنچه نکرو دربارهی باتها و وبهوکها به اعضایش میگوید در سیاست حریم خصوصی آمده است.