احراز هویت و توکن‌ها

API عمومی با توکن‌های دسترسی شخصی (PAT) احراز هویت می‌شود. یک توکن به حساب متصل است و در محدوده حوزه‌های دسترسی اعطاشده، روی تمام موجودیت‌های سازنده شما عمل می‌کند.

ایجاد توکن

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

تمام توکن‌های شخصی با پیشوند mbp_ شروع می‌شوند.

ارسال توکن

توکن در هر درخواست از طریق هدر HTTP به شکل Bearer ارسال می‌شود:

Authorization: Bearer mbp_TOKEN_SHOMA

همین هدر برای دسترسی جلسه‌ای از پنل وب نیز استفاده می‌شود (آنجا JWT کوتاه‌مدت است)، اما برای یکپارچه‌سازی‌ها از توکن شخصی mbp_… استفاده کنید.

حوزه‌های دسترسی (scopes)

هر توکن مجموعه‌ای از حوزه‌های دسترسی به فرم resource:action دارد. خواندن نیاز به پسوند :read، تغییرات به :write دارد. حوزه‌های موجود:

  • bots:read، bots:write — بات‌ها، تنظیمات آن‌ها، همگام‌سازی، توکن بات.
  • reactions:read، reactions:write — واکنش‌ها، ورودی، آزمون فرمول‌ها، پیوندها، ترتیب.
  • labels:read، labels:write — برچسب‌های مشترکان.
  • collections:read، collections:write — مجموعه‌ها و رکوردها.
  • flows:read، flows:write — سناریوها.
  • integrations:read، integrations:write — یکپارچه‌سازی‌ها، اتصالات، اطلاعات اعتباری.
  • media:write — آپلود به کتابخانه رسانه.
  • templates:read، templates:write — قالب‌های بات.
  • settings:read، settings:write — تنظیمات.
  • subscribers:read — مشترکان و تاریخچه مکالمه (فقط خواندن).
  • broadcasts:write — همه‌رسانی‌ها و مدیریت آن‌ها.
  • stats:read — آمار و تحلیل‌ها.
  • billing:read — موجودی و طرح‌ها (فقط خواندن).

حوزه ویژه * دسترسی کامل به تمام اندپوینت‌های عمومی می‌دهد.

آنچه با توکن در دسترس است و آنچه نیست

با توکن شخصی فقط اندپوینت‌های سازنده در دسترس هستند — آن‌هایی که «به ساخت بات کمک می‌کنند». از طریق PAT در دسترس نیست (فقط از جلسه وب): ورود و ثبت‌نام، اندپوینت‌های موبایل، پرداخت و شارژ موجودی، اعلان‌ها، گزارش ممیزی، ارسال اپراتوری به مکالمه، وب‌هوک‌های ورودی و کالبک‌های پرداخت، WebSocket. درخواست با توکن mbp_ به چنین مسیری 401 یا 403 برمی‌گرداند.

اگر حوزه لازم برای مسیر خاصی در توکن وجود نداشته باشد — 403 برمی‌گردد. جزئیات بیشتر در راهنمای خطاها.

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