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

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

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

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

Header	مقدار	توضیحات
`X-Api-Key`	`YOUR_ACCESS_TOKEN`	توکن دسترسی اختصاصی شما. این توکن را می‌توانید از بخش «تنظیمات API» در پنل کاربری BoxAPI دریافت کنید.

نکته امنیتی: توکن دسترسی خود را هرگز در کدهای سمت کلاینت (Frontend) یا مخازن عمومی قرار ندهید. تمامی درخواست‌ها باید از سمت سرور (Backend) ارسال شوند.

وبهوک (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"
  }
]

راهنما: مقدار data.messaging[].sender.id همان recipient_id است که در اندپوینت ارسال پیام (send_message) استفاده می‌شود.

دامنه (Domain) و Redirect URL

دامنه سرویس

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

Redirect URL

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

محدودیت مهم: مقدار Redirect URL باید زیرمجموعه‌ای از Domain ثبت‌شده شما باشد و امکان تعیین آدرسی خارج از دامنه ثبت‌شده وجود ندارد.

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

GET
/service/info

اطلاعات کامل حساب کاربری، پلن اشتراک، تنظیمات دامنه/ریدایرکت و لیست پیج‌های متصل را برمی‌گرداند.

پارامترها

نام	محل	نوع	الزامی	توضیحات
`X-Api-Key`	Header	string	بله	توکن دسترسی کاربر

نمونه پاسخ ۲۰۰ OK

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

توضیح فیلدهای پاسخ

فیلد	توضیحات
`data.domain`	دامنه ثبت‌شده کاربر (یا مقدار پیش‌فرض `boxapi.ir`)
`data.token`	توکن دسترسی فعلی کاربر (`X-Api-Key`)
`data.login_redirect_url`	آدرس ریدایرکت پس از ورود موفق کاربر به اینستاگرام
`data.instagram_oauth_url`	لینک اختصاصی ورود رسمی اینستاگرام برای اتصال پیج جدید
`data.plan`	اطلاعات پلن اشتراک فعلی از جمله سقف تعداد پیج مجاز (`account_limit`)
`data.accounts`	لیست پیج‌های اینستاگرام متصل‌شده به این حساب

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

POST
/service/actions/send_message

این اندپوینت برای ارسال پیام متنی یا پیام دکمه‌دار (Button Template) در دایرکت اینستاگرام استفاده می‌شود.

پارامترهای بدنه درخواست (Body)

نام	نوع	الزامی	توضیحات
`account_id`	string (UUID)	بله	آیدی پیج اینستاگرامی که پیام از طریق آن ارسال می‌شود (از خروجی `/service/accounts`)
`recipient_id`	string	بله	آیدی گیرنده پیام. این مقدار از فیلد `sender.id` در Webhook دریافت می‌شود
`message`	string	بله	متن پیام ارسالی
`buttons`	array	خیر	آرایه‌ای از دکمه‌ها برای ارسال پیام تعاملی (اختیاری)

ساختار هر آیتم در آرایه buttons

نام	نوع	توضیحات
`type`	string	نوع دکمه؛ مقادیر مجاز: `postback` یا `web_url`
`title`	string	عنوان نمایشی دکمه
`payload`	string	مقدار بازگشتی هنگام کلیک (فقط برای نوع `postback`)
`url`	string	آدرس مقصد (فقط برای نوع `web_url`)

نمونه درخواست ساده

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

پاسخ به کامنت

POST
/service/actions/reply_comment

این اندپوینت برای ارسال پاسخ (ریپلای) به یک کامنت مشخص روی پست اینستاگرام استفاده می‌شود.

پارامترهای بدنه درخواست (Body)

نام	نوع	الزامی	توضیحات
`account_id`	string (UUID)	بله	آیدی پیج اینستاگرامی که کامنت روی پست آن قرار دارد
`comment_id`	string	بله	آیدی کامنت مورد نظر؛ این مقدار از طریق Webhook دریافت می‌شود
`message`	string	بله	متن پاسخ کامنت

نمونه درخواست

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

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

POST
/service/actions/follow_status

این اندپوینت مشخص می‌کند که آیا کاربری که پیام یا کامنت ارسال کرده، پیج مورد نظر را فالو کرده است یا خیر. این اندپوینت به‌صورت آسنکرون کار می‌کند.

پارامترهای بدنه درخواست (Body)

نام	نوع	الزامی	توضیحات
`account_id`	string (UUID)	بله	آیدی پیج اینستاگرامی مبدأ بررسی
`customer_id`	string	بله	آیدی کاربری که وضعیت فالوی او بررسی می‌شود (همان آیدی ارسال‌کننده پیام یا کامنت)

نمونه درخواست

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

پاسخ: این اندپوینت پاسخ فوری بازنمی‌گرداند؛ نتیجه بررسی پس از پردازش از طریق آدرس Webhook ثبت‌شده شما ارسال خواهد شد.

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

POST
/service/actions/list_posts

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

پارامترهای بدنه درخواست (Body)

نام	نوع	الزامی	توضیحات
`account_id`	string (UUID)	بله	آیدی پیج اینستاگرامی مورد نظر
`fields`	array of string	خیر	لیست فیلدهایی که برای هر پست بازگردانده شود؛ مثال: `id`, `media_type`, `media_url`, `permalink`, `caption`, `timestamp`
`limit`	number	خیر	تعداد پست‌های بازگشتی

نمونه درخواست

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

پاسخ: نتیجه نهایی این درخواست از طریق Webhook برای شما ارسال خواهد شد، نه در پاسخ مستقیم HTTP.

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

GET
/service/accounts

این اندپوینت اطلاعات تمامی پیج‌هایی که از طریق لینک ورود اختصاصی شما (instagram_oauth_url) لاگین شده‌اند را به‌صورت صفحه‌بندی‌شده برمی‌گرداند.

نمونه پاسخ ۲۰۰ OK

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

توضیح فیلدهای هر پیج

فیلد	توضیحات
`id`	آیدی داخلی پیج؛ همان مقداری که در سایر اندپوینت‌ها به‌عنوان `account_id` استفاده می‌شود
`username`	نام کاربری پیج اینستاگرام
`instagram_user_id`	آیدی عددی رسمی پیج در اینستاگرام
`is_active`	وضعیت فعال بودن اتصال پیج
`expires_at`	تاریخ انقضای دسترسی پیج؛ در صورت انقضا نیاز به ورود مجدد است

حذف پیج

DELETE
/service/accounts/{id}

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

پارامترهای مسیر (Path Parameters)

نام	نوع	الزامی	توضیحات
`id`	string (UUID)	بله	همان `account_id` پیج مورد نظر برای حذف

نمونه پاسخ ۲۰۰ OK

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

هشدار (عملیات غیرقابل بازگشت): با حذف پیج، تمامی اطلاعات مربوط به آن حتی در سمت BoxAPI (SendBox) نیز به‌طور کامل حذف می‌شود و تا زمان ورود مجدد، دیگر دسترسی به آن پیج نخواهید داشت.

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

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

No code available.

No JSON input available.