Skip to navigation
راهنماها

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

نسخه پیش‌انتشار v1، منتشرشده در ۲۰۲۶-۰۹-۱۴. این صفحه شکل API را تعهد می‌کند، نه تاریخ آن را. دقیقاً همین چیزی را که این‌جا مستند شده می‌سازیم. شکل API تا ۲۰۲۶-۱۰-۱۴ هنوز ممکن است تغییر کند؛ پس از آن، تغییرات از نسخه‌بندی و پایداری پیروی می‌کنند.

این بنر صفحه‌به‌صفحه و هم‌زمان با فعال‌شدن هر مسیر برداشته می‌شود. تا وقتی این‌جاست، بر اساس قرارداد پیاده‌سازی کنید و فرض کنید این مسیر هنوز قابل فراخوانی نیست.

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

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

{
  "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 می‌شود و تا آن زمان هیچ ظرفیتی اشغال نمی‌کند.

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

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

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

فراخوانی اندپوینت بدون آدرس بازگشت، خطای 422 return_url_not_configured برمی‌گرداند.

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

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

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

روند کار

1. POST /v1/robots/{id}/channels {"type":"instagram"} 2. authorisation_url 3. send the owner to authorisation_url 4. the owner authorises the page 5. authorisation completed 6. redirect to YOUR return_url (service_id + status) 7. owner lands back on your panel 8. GET /v1/robots/{id}/channels to confirm Page owner's browser Your panel ParsChat Instagram

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

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

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

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

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

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

خطاها

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

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

قطع اتصال

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

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