مستندات API دایرکت اینستاگرام (رسمی)

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

احراز هویت (Authentication)

تمامی اندپوینت‌های این API از روش احراز هویت مبتنی بر هدر استفاده می‌کنند. برای هر درخواست باید هدر زیر را ارسال کنید:

وبهوک (Webhook)

برای دریافت رویدادهای لحظه‌ای مانند پیام‌های دایرکت، کامنت‌ها و پاسخ اکشن‌های آسنکرون (مانند follow_status و list_posts)، باید یک آدرس Webhook در بخش «تنظیمات API» پنل کاربری خود ثبت کنید.

• آدرس Webhook می‌تواند متعلق به سرویس اختصاصی شما، وبهوک n8n یا هر نرم‌افزار اتوماسیون دیگری باشد.
• متد ارسال درخواست به Webhook می‌تواند POST یا GET باشد.

نمونه Webhook:

[
  {
    "headers": {
      "host": "https://YOURWEBSITE.COM",
      "x-real-ip": "1.1.1.1",
      "content-type": "application/json"
    },
    "params": {},
    "query": {},
    "body": {
      "event_id": "client_ig_111111111_1111111116",
      "event_type": "messaging",
      "account_id": "00000000-0000-0000-0000-000000000000",
      "data": {
        "time": 1785081317446,
        "id": "1234567890",
        "messaging": [
          {
            "sender": { "id": "1234567890" },
            "recipient": { "id": "1234567890" },
            "timestamp": 1785081317081,
            "message": {
              "mid": "abcxyz",
              "text": "سلام"
            }
          }
        ]
      }
    },
    "webhookUrl": "https://YOURWEBSITE.COM/webhook/zzzzzzzz",
    "executionMode": "test"
  }
]

دامنه (Domain) و Redirect URL

دامنه سرویس

دامنه سرویس شما باید در پنل کاربری ثبت شود. در صورتی که دامنه‌ای ثبت نکرده باشید، به‌صورت پیش‌فرض مقدار https://boxapi.ir در نظر گرفته می‌شود.

Redirect URL

در بخش «تنظیمات API» می‌توانید یک Redirect URL تعریف کنید. کاربران پس از ورود موفق به پیج اینستاگرام خود (از طریق لینک ورود رسمی اینستاگرام) به این آدرس هدایت می‌شوند.

دریافت اطلاعات سرویس

{
  "success": true,
  "message": "string",
  "status_code": 0,
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "domain": "string",
    "token": "string",
    "login_redirect_url": "string",
    "instagram_oauth_url": "string",
    "user": {
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "string",
      "email": "string",
      "phone_number": "string"
    },
    "plan": {
      "name": "string",
      "slug": "string",
      "description": "string",
      "account_limit": 0,
      "price": 0,
      "duration_days": 0,
      "items": ["string"]
    },
    "accounts": [
      {
        "id": "00000000-0000-0000-0000-000000000000",
        "username": "string",
        "instagram_user_id": "string",
        "profile_photo": "string",
        "internal_token": "string",
        "is_active": true,
        "expires_at": "2026-07-26T15:40:14.480Z"
      }
    ]
  }
}

ارسال پیام دایرکت

{
  "account_id": "00000000-0000-0000-0000-000000000000",
  "recipient_id": "1234567890",
  "message": "Hello"
}

{
  "account_id": "00000000-0000-0000-0000-000000000000",
  "recipient_id": "1234567890",
  "message": "برای ادامه یکی را انتخاب کنید",
  "buttons": [
    { "type": "postback", "title": "شروع", "payload": "START" },
    { "type": "web_url", "title": "سایت", "url": "https://example.com" }
  ]
}

پاسخ به کامنت

{
  "account_id": "00000000-0000-0000-0000-000000000000",
  "comment_id": "1234567890",
  "message": "پاسخ کامنت"
}

بررسی وضعیت فالو

{
  "account_id": "00000000-0000-0000-0000-000000000000",
  "customer_id": "1234567890"
}

دریافت لیست پست‌ها

{
  "account_id": "00000000-0000-0000-0000-000000000000",
  "fields": ["id", "media_type", "media_url", "permalink", "caption", "timestamp"],
  "limit": 10
}

دریافت لیست پیج‌های متصل

{
  "success": true,
  "message": "string",
  "status_code": 0,
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "username": "string",
      "instagram_user_id": "string",
      "profile_photo": "string",
      "internal_token": "string",
      "is_active": true,
      "expires_at": "2026-07-26T19:49:40.273Z"
    }
  ],
  "pagination": {
    "current_page": 0,
    "last_page": 0,
    "per_page": 0,
    "total": 0,
    "from": 0,
    "to": 0
  }
}

مشاهده پروفایل کاربر

{
  "sender_id": "1111111111111111111",
  "account_id": "2222222222"
}

حذف پیج

{
  "success": true,
  "message": "Account deleted successfully",
  "status_code": 200,
  "data": null
}

محدودیت درخواست (Rate Limit)

محدودیت ارسال درخواست در BoxAPI دقیقاً بر مبنای همان محدودیت‌های رسمی «Instagram API with Instagram Login» متعلق به متا (Meta for Developers) اعمال می‌شود. این محدودیت‌ها به‌صورت جداگانه برای هر پیج اینستاگرامی (Instagram Professional Account) محاسبه می‌شوند، نه به‌صورت استخر مشترک بین پیج‌ها.

محدودیت پیام دایرکت (send_message)

محدودیت پاسخ به کامنت (reply_comment)

پاسخ‌های ارسالی به کامنت‌های پست و ریلز (Private Reply) با نرخ ساعتی محدود می‌شوند، نه ثانیه‌ای:

نحوه محاسبه در حساب‌های چندپیجی

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

مدیریت خودکار توسط BoxAPI

نیازی به محاسبه دستی یا مدیریت این سهمیه از سمت شما نیست؛ سیستم BoxAPI به‌صورت خودکار مصرف درخواست‌های هر پیج را پایش می‌کند و در صورت نزدیک شدن به سقف مجاز، مانع از بروز خطا در سمت سیستم شما می‌شود. درخواست‌های مازاد بر سهمیه لحظه‌ای، به‌جای رد شدن، در صف قرار گرفته و پس از آزاد شدن ظرفیت (باز شدن پنجره ثانیه‌ای یا ساعتی) به‌صورت خودکار ارسال می‌شوند.

نکات مهم و حریم خصوصی

• حذف دسترسی از سمت کاربر اینستاگرام: در صورتی که کاربر نهایی دسترسی سرویس را از تنظیمات اینستاگرام خود حذف کند، یا درخواست حذف به BoxAPI ارسال شود، این عملیات بدون اطلاع‌رسانی قبلی انجام خواهد شد.
• پاک‌سازی کامل اطلاعات: در صورت حذف دسترسی پیج — چه از سمت کاربر، چه از سمت BoxAPI و چه از سمت شما — اطلاعات آن پیج به‌طور کامل و غیرقابل بازگشت حذف می‌شود.
• حریم خصوصی داده‌ها: هیچ‌یک از اطلاعات کاربران به‌صورت مستقیم از سمت اینستاگرام در اختیار شما (توسعه‌دهنده) قرار نمی‌گیرد؛ تمامی اطلاعات صرفاً نزد BoxAPI نگهداری و پردازش می‌شود.
• عدم امکان ارسال پیام انبوه: ساخت ربات ارسال پیام انبوه (Bulk Messaging) در اینستاگرام از طریق این سرویس امکان‌پذیر نیست. صرفاً امکان ارسال پیام به کاربرانی وجود دارد که پیش‌تر با پیج شما تعامل داشته‌اند؛ یعنی کامنتی گذاشته‌اند یا پیامی در دایرکت ارسال کرده‌اند. در صورت شناسایی رفتار اسپم‌گونه، حساب کاربری بسته خواهد شد.
• تخلف و قطع دسترسی: در صورت مشاهده هرگونه تخلف از قوانین استفاده از این API، BoxAPI می‌تواند دسترسی شما به سرویس را بدون اطلاع قبلی و به‌طور یک‌طرفه قطع کند.