> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-parschat.parstechai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-parschat.parstechai.com/_mcp/server.

# اتصال اینستاگرام

> به‌جای یک فراخوانی API، یک ریدایرکت در مرورگر؛ به‌همراه آدرس بازگشتی که مشتری شما را به پنل خودتان برمی‌گرداند.

> **Warning**
>
> **نسخه پیش‌انتشار `v1`، منتشرشده در ۲۰۲۶-۰۹-۱۴.** این صفحه شکل API را تعهد می‌کند، نه تاریخ
> آن را. دقیقاً همین چیزی را که این‌جا مستند شده می‌سازیم. شکل API تا **۲۰۲۶-۱۰-۱۴** هنوز ممکن است
> تغییر کند؛ پس از آن، تغییرات از [نسخه‌بندی و پایداری](/documentation/reference/versioning-stability) پیروی می‌کنند.
>
> این بنر صفحه‌به‌صفحه و هم‌زمان با فعال‌شدن هر مسیر برداشته می‌شود. تا وقتی این‌جاست، بر اساس
> قرارداد پیاده‌سازی کنید و فرض کنید این مسیر هنوز قابل فراخوانی نیست.

## چرا این کار با یک فراخوانی API انجام نمی‌شود

یک صفحه اینستاگرام را نمی‌توان با توکنی که از قبل در اختیار دارید متصل کرد. Meta از **مالک صفحه**
می‌خواهد که در مرورگر خودش اجازه دسترسی بدهد. بنابراین `POST /v1/robots/{id}/channels` با
`"type": "instagram"` چیزی را متصل نمی‌کند؛ بلکه **یک فرایند دست‌دهی (handshake) را آغاز می‌کند** و
آدرسی برمی‌گرداند که باید مالک صفحه را به آن بفرستید.

```json
{
  "id": "chn_3pQ7xL",
  "type": "instagram",
  "robot_id": "rbt_8fK2mQ",
  "status": "pending_authorisation",
  "authorisation_url": "https://connect.parstechai.com/authorise?service_id=svc_4dR8nW",
  "expires_at": "2026-09-20T12:04:33Z"
}
```

`authorisation_url` را در مرورگر مالک صفحه باز کنید. کانال فقط وقتی مالک این مرحله را تمام کند
`is_active: true` می‌شود و **تا آن زمان هیچ ظرفیتی اشغال نمی‌کند**.

> **Warning**
>
> **`authorisation_url` را یک مقدار مبهم و دست‌نخوردنی در نظر بگیرید و دقیقاً همان‌طور که برگشته به آن
> ریدایرکت کنید.** این آدرس از `api-chat.parstechai.com` ارائه نمی‌شود، میزبان و مسیر آن بخشی از
> قرارداد این API نیستند و وضعیتی را با خود حمل می‌کند که باید در رفت‌وبرگشت سالم بماند. آن را
> نسازید، تجزیه نکنید، میزبانش را بازنویسی نکنید و رشته کوئری آن را حذف نکنید.

## اول آدرس بازگشت را تنظیم کنید

> **Warning**
>
> **پیش از اولین اتصال، آدرس بازگشت خود را به ما اعلام کنید.** اگر آدرسی تنظیم نشده باشد، این فرایند
> مشتری شما را به داشبورد **ما** می‌فرستد: صفحه‌ای از پارس‌چت که هرگز ندیده، آن هم وسط ثبت‌نام و در
> محصولی که فکر می‌کند متعلق به شماست.
>
> فراخوانی اندپوینت بدون آدرس بازگشت، خطای `422 return_url_not_configured` برمی‌گرداند.

| آدرس            | کاربرد                                                       | فراخوان           |
| --------------- | ------------------------------------------------------------ | ----------------- |
| **آدرس وب‌هوک** | دریافت رویدادها، سرور به سرور                                | ما ← سرور شما     |
| **آدرس بازگشت** | جایی که **مرورگر** مالک صفحه پس از اجازه دسترسی به آن می‌رسد | مرورگر ← سایت شما |

آدرس وب‌هوک را خودتان در پنل پارس‌چت تنظیم می‌کنید. آدرس بازگشت را باید به ما بدهید: چون مرورگر یک
شخص به آن فرستاده می‌شود، اگر از طریق یک اندپوینت قابل تغییر بود، یک کلید دزدیده‌شده به ابزاری برای
ریدایرکت باز (open redirect) و فیشینگ تبدیل می‌شد.

> **Info**
>
> **آدرس بازگشت باید با آدرس وب‌هوک شما هم‌مبدأ (same origin) باشد** و از `https` استفاده کند. این
> الزام اجباری است، نه یک توصیه. همین است که فرستادن مالک صفحه به یک سایت نامرتبط را ناممکن می‌کند.

## روند کار

```mermaid
sequenceDiagram
    participant C as Page owner's browser
    participant P as Your panel
    participant PC as ParsChat
    participant Meta as Instagram

    P->>PC: 1. POST /v1/robots/{id}/channels {"type":"instagram"}
    PC-->>P: 2. authorisation_url
    P->>C: 3. send the owner to authorisation_url
    C->>Meta: 4. the owner authorises the page
    Meta-->>PC: 5. authorisation completed
    PC->>C: 6. redirect to YOUR return_url (service_id + status)
    C->>P: 7. owner lands back on your panel
    P->>PC: 8. GET /v1/robots/{id}/channels to confirm
```

مراحل ۱ تا ۳ با شماست. مراحل ۴ تا ۷ در مرورگر مالک صفحه انجام می‌شود و شما در آن نقشی ندارید.
مرحله ۸ دوباره با شماست: به‌جای اعتماد به رسیدن مرورگر، فعال‌بودن کانال را تأیید کنید.

> **Info**
>
> همه کارهای بین مرحله ۳ و مرحله ۶، از جمله تبادل توکن و اشتراک رویدادها، برای شما انجام می‌شود.
> شما هرگز توکن اینستاگرام را نمی‌بینید و ذخیره نمی‌کنید.

### آنچه به آدرس بازگشت شما می‌رسد

مرورگر با `service_id` و یک وضعیت، به‌صورت پارامترهای کوئری، به صفحه شما می‌رسد:

```
https://partner.example/instagram/done?service_id=svc_4dR8nW&status=success
```

صفحه موفقیت یا شکست خودتان را بر اساس آن نمایش دهید. رسیدن مرورگر را دلیلی بر فعال‌بودن کانال
ندانید. با `GET /v1/robots/{robot_id}/channels` آن را تأیید کنید.

## خطاها

| وضعیت | `code`                      | معنی                                                         |
| ----- | --------------------------- | ------------------------------------------------------------ |
| `422` | `return_url_not_configured` | هنوز آدرس بازگشتی برای شما تنظیم نشده است. با ما تماس بگیرید |
| `409` | `handshake_pending`         | برای این ربات یک فرایند دست‌دهی منقضی‌نشده از قبل وجود دارد  |
| `410` | `handshake_expired`         | مالک بیش از حد طول داد؛ فرایند جدیدی را آغاز کنید            |
| `403` | `channel_not_in_plan`       | بسته شما شامل اینستاگرام نیست                                |
| `409` | `conflict`                  | این ربات از قبل یک کانال اینستاگرام دارد                     |

> **Info**
>
> هر فرایند دست‌دهی حدود یک ساعت پس از آغاز منقضی می‌شود. اگر مشتری شما روند را نیمه‌کاره رها کرد و
> بعداً برگشت، کافی است دوباره `POST …/channels` را فراخوانی کنید تا یک `authorisation_url` تازه
> بگیرید.

## قطع اتصال

```bash
curl -X DELETE https://api-chat.parstechai.com/v1/robots/rbt_8fK2mQ/channels/chn_3pQ7xL \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxx"
```

پاسخ `204 No Content` است. ظرفیت بلافاصله آزاد می‌شود. **گفتگوها و تاریخچه حذف نمی‌شوند.**
آن‌ها پس از قطع اتصال و اتصال دوباره در آینده باقی می‌مانند.