# مستندات API دایرکت و کامنت اینستاگرام (BoxAPI / SendBox)

> منبع: `https://boxapi.ir/docs/instagram/instagram-official-api/`
> این سند مرجع کامل اتصال به سرویس دایرکت و کامنت اینستاگرام از طریق BoxAPI (SendBox) است. تمامی اندپوینت‌ها، پارامترهای ورودی، و نمونه‌های درخواست/پاسخ در ادامه آمده‌اند.

**Base URL (استنباط‌شده از مسیرهای نسبی سند):** مسیرهای زیر همگی نسبی هستند (مثلاً `/service/info`). دامنه پایه در مستندات اصلی ذکر نشده؛ پیش از استفاده با دامنه سرویس BoxAPI (مثلاً `https://boxapi.ir` یا زیردامنه اختصاصی سرویس دایرکت) ترکیب شود.


## 1. احراز هویت (Authentication)

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

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

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

---

## 2. وبهوک (Webhook)

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

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

### نمونه بدنه درخواست ارسالی به Webhook

```json
[
  {
    "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.body.data.messaging[].sender.id` همان `recipient_id` است که در اندپوینت ارسال پیام (`send_message`) استفاده می‌شود.

---

## 3. دامنه (Domain) و Redirect URL

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

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

> ⚠️ **محدودیت مهم:** مقدار `Redirect URL` باید زیرمجموعه‌ای از `Domain` ثبت‌شده باشد؛ تعیین آدرسی خارج از دامنه ثبت‌شده امکان‌پذیر نیست.

---

## 4. `GET /service/info` — دریافت اطلاعات سرویس

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

### پارامترها

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

### نمونه پاسخ `200 OK`

```json
{
  "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` | لیست پیج‌های اینستاگرام متصل‌شده به این حساب |

---

## 5. `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`) |

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

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

### نمونه درخواست همراه با دکمه

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

---

## 6. `POST /service/actions/reply_comment` — پاسخ به کامنت

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

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

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

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

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

---

## 7. `POST /service/actions/follow_status` — بررسی وضعیت فالو

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

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

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

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

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

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

---

## 8. `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 | خیر | تعداد پست‌های بازگشتی |

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

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

> ℹ️ **پاسخ:** نتیجه نهایی این درخواست از طریق Webhook ارسال می‌شود، نه در پاسخ مستقیم HTTP.

---

## 9. `GET /service/accounts` — دریافت لیست پیج‌های متصل

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

### نمونه پاسخ `200 OK`

```json
{
  "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` | تاریخ انقضای دسترسی پیج؛ در صورت انقضا نیاز به ورود مجدد است |

---

## 10. `DELETE /service/accounts/{id}` — حذف پیج

حذف کامل یک پیج از حساب کاربری.

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

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

### نمونه پاسخ `200 OK`

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

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

---

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

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

---

## خلاصه اندپوینت‌ها (برای مرجع سریع)

| Method | Path | نوع پاسخ | توضیح کوتاه |
|---|---|---|---|
| GET | `/service/info` | همزمان (Sync) | اطلاعات حساب، پلن، دامنه، پیج‌ها |
| POST | `/service/actions/send_message` | همزمان (Sync) | ارسال پیام دایرکت (متنی/دکمه‌دار) |
| POST | `/service/actions/reply_comment` | همزمان (Sync) | پاسخ به کامنت پست |
| POST | `/service/actions/follow_status` | آسنکرون (نتیجه از Webhook) | بررسی فالو بودن کاربر |
| POST | `/service/actions/list_posts` | آسنکرون (نتیجه از Webhook) | دریافت لیست پست‌های پیج |
| GET | `/service/accounts` | همزمان (Sync), Paginated | لیست پیج‌های متصل |
| DELETE | `/service/accounts/{id}` | همزمان (Sync) | حذف یک پیج متصل |

همه اندپوینت‌ها نیازمند هدر `X-Api-Key` هستند.