شروع سریع API

این راهنما شما را از صفر تا اولین درخواست موفق هدایت می‌کند: ایجاد توکن شخصی، یافتن آدرس پایه و فراخوانی اندپوینت REST.

مرحله ۱. ایجاد توکن شخصی

پنل کاربری، بخش توکن‌های شخصی را باز کنید و یک توکن جدید (PAT) بسازید. مقدار آن را فوری کپی کنید — یک بار نمایش داده می‌شود و با پیشوند mbp_ شروع می‌شود. در زمان ایجاد، حوزه‌های دسترسی (scopes) کافی برای کارتان را انتخاب کنید؛ جزئیات بیشتر در راهنمای احراز هویت.

مرحله ۲. آدرس پایه و فرمت

همه اندپوینت‌های REST زیر پیشوند /api قرار دارند. نسخه‌بندی در مسیر وجود ندارد. بدنه درخواست‌ها و پاسخ‌ها JSON هستند؛ هدر Content-Type: application/json را برای درخواست‌های با بدنه ارسال کنید. توکن از طریق هدر Authorization: Bearer mbp_… ارسال می‌شود.

مرحله ۳. اولین درخواست — فهرست بات‌ها

توکن را با درخواست فهرست بات‌هایتان آزمایش کنید. برای این کار scope bots:read (یا *) لازم است:

curl -H "Authorization: Bearer mbp_TOKEN_SHOMA" https://your-domain/api/bots

در پاسخ یک آرایه JSON از بات‌ها می‌آید. اگر توکن نادرست یا منقضی باشد — 401 با بدنه {"error":"..."} برمی‌گردد (ببینید خطاها).

مرحله ۴. اولین تغییر — ایجاد واکنش

ایجاد واکنش به scope reactions:write نیاز دارد. شناسه بات از مرحله ۳ را جایگزین کنید:

curl -X POST -H "Authorization: Bearer mbp_TOKEN_SHOMA" -H "Content-Type: application/json" -d '{"name":"سلام","trigger":{"type":"command","value":"/start"}}' https://your-domain/api/bots/BOT_ID/reactions

پاسخ موفق واکنش ایجادشده را با id آن برمی‌گرداند. فیلدهای دقیق بدنه را در مرجع تعاملی ببینید — نمونه‌های آماده برای curl، JavaScript و Python برای هر اندپوینت تولید می‌کند.

مرحله ۵. ادامه — با مرجع

وقتی توکن کار می‌کند، بقیه را راحت‌تر می‌توان در مرجع تعاملی بررسی کرد: فهرست کامل اندپوینت‌ها، scopes موردنیاز، طرح‌های بدنه و دکمه «Try it» موجود است.

بیشتر بخوانید