راهنمای صفر تا صد تنظیم اپ متا برای ویجنت

پیش‌نیازها

• یک اکانت Meta Developer (از developers.facebook.com)
• یک دامنه با HTTPS (مثلاً vigent.ir)
• سرور با قابلیت دریافت وب‌هوک عمومی

۱. ساخت اپ

1. 1به developers.facebook.com ← My Apps بروید و روی Create App بزنید.
2. 2نوع اپ را Business انتخاب کنید.
3. 3نام اپ را vigent-IG (یا نام برند خود) وارد کنید و ایمیل تماس را بنویسید.
4. 4روی Create App بزنید.

۲. افزودن محصول Instagram

در داشبورد اپ، از بخش Add Products، محصول Instagram Platform را پیدا کنید و Set Up را بزنید. سپس در بین گزینه‌ها، «Instagram API with Instagram Login» را انتخاب کنید — نه Facebook Login. این همان جریان Business Login for Instagram است که از ژوئیه ۲۰۲۴ در دسترس است و به کاربر اجازه می‌دهد مستقیم با اکانت اینستاگرام خود وارد شود، بدون اینکه به فیسبوک برود یا صفحه فیسبوک انتخاب کند.

۳. تنظیمات Basic

• Display Name: vigent-IG
• App Domains: vigent.ir
• Privacy Policy URL: https://vigent.ir/privacy
• Terms of Service URL: https://vigent.ir/terms
• App Icon (1024×1024)

۴. تنظیمات OAuth (Instagram Login)

در منوی سمت چپ اپ، به Instagram ← API Setup with Instagram Login بروید. در این صفحه بخش «Valid OAuth Redirect URIs» را پیدا کنید و آدرس زیر را اضافه کنید:

https://vigent.ir/api/instagram/oauth/callback

• Deauthorize Callback URL: https://vigent.ir/api/instagram/deauthorize
• Data Deletion Request URL: https://vigent.ir/api/instagram/data-deletion

۵. تنظیمات وب‌هوک (Webhook)

وب‌هوک را یک‌بار در اپ تنظیم کنید. Callback URL: https://vigent.ir/api/webhook/instagram — Verify Token: مقدار META_APP_VERIFY_TOKEN که در env تنظیم کرده‌اید. فیلدهای subscribe: messages، messaging_postbacks، comments، mentions. منشن استوری از طریق messages و به‌شکل attachment با نوع story_mention دریافت می‌شود. در جریان Instagram Login، وقتی کاربر اکانت خود را وصل می‌کند، اکانت اینستاگرام او به‌صورت خودکار به این وب‌هوک subscribe می‌شود — هیچ فراخوانی subscribePageToApp لازم نیست (برخلاف جریان قدیمی فیسبوک).

۶. App Review (برای Advanced Access)

برای اینکه همه کاربران (نه فقط tester) بتوانند اکانت خود را وصل کنند و دایرکت/کامنت بگیرند، باید scope‌های زیر را به Advanced Access ارتقا دهید. توجه کنید که نام scope‌ها از ۲۷ ژانویه ۲۰۲۵ تغییر کرده و نسخه‌های قدیمی (مثل instagram_basic، instagram_manage_messages و instagram_manage_comments) منسوخ شده‌اند — حالا همه با پیشوند instagram_business_ شروع می‌شوند:

• instagram_business_basic — دسترسی پایه به پروفایل و اطلاعات اکانت
• instagram_business_manage_messages — نیاز به App Review و screencast (خواندن و پاسخ به دایرکت)
• instagram_business_manage_comments — نیاز به App Review (خواندن و پاسخ به کامنت‌ها)

۷. App Mode: Live

بعد از تکمیل App Review و تنظیم Privacy Policy + Data Deletion، اپ را از Development به Live ببرید. تا زمان Live بودن، فقط tester/admin می‌توانند اتصال را تست کنند.

۸. Data Deletion Callback

متا الزام می‌کند که URLی برای حذف داده کاربر تعریف کنید. در App Settings ← Advanced ← Data Deletion Callback URL: https://vigent.ir/api/instagram/data-deletion. این endpoint باید POST با signed_request دریافت کند و یک confirmation code برگرداند. (این endpoint توسط تیم ویجنت پیاده‌سازی می‌شود.)

۹. متغیرهای محیطی (env)

META_APP_ID=1234567890
META_APP_SECRET=abcdef1234567890...
META_APP_VERIFY_TOKEN=your_random_verify_token_string
NEXT_PUBLIC_APP_URL=https://vigent.ir
ENCRYPTION_KEY=<openssl rand -hex 32>

۱۰. جزئیات فنی جریان OAuth

ویجنت از endpointهای رسمی Instagram Login استفاده می‌کند (نه endpointهای فیسبوک):

# 1) Authorize (browser)
GET https://api.instagram.com/oauth/authorize
    ?client_id={META_APP_ID}
    &redirect_uri=https://vigent.ir/api/instagram/oauth/callback
    &scope=instagram_business_basic,instagram_business_manage_messages,instagram_business_manage_comments
    &response_type=code

# 2) Exchange code for short-lived token
POST https://api.instagram.com/oauth/access_token

# 3) Exchange to long-lived token (60 days)
GET https://graph.instagram.com/access_token
    ?grant_type=ig_exchange_token
    &client_secret={META_APP_SECRET}

# 4) Send a DM (Instagram Messaging API, Messenger Platform format)
POST https://graph.instagram.com/v21.0/me/messages

• تمام فراخوانی‌های Graph به graph.instagram.com می‌روند، نه graph.facebook.com.
• دایرکت‌ها از طریق Instagram Messaging API با همان فرمت Messenger Platform ارسال می‌شوند (POST /me/messages).
• توکن بلندمدت هر ۶۰ روز یک‌بار باید refresh شود (GET graph.instagram.com/refresh_access_token).

۱۱. واتساپ (WhatsApp Cloud API)

واتساپ هم چون محصول متا است، از همان اپ استفاده می‌کند. محصول WhatsApp Business API را به اپ اضافه کنید، شماره تلفن config کنید، و permission‌های whatsapp_business_messaging و whatsapp_business_management را App Review بزنید. Redirect URI واتساپ: https://vigent.ir/api/whatsapp/oauth/callback. (واتساپ از Facebook Login با Embedded Signup استفاده می‌کند — این جریان جدا از Instagram Login است.)

۱۲. تست اتصال

1. 1در اپ متا، Roles ← Instagram Testers ← خودتان را اضافه کنید (در حال Development).
2. 2درخواست tester را در اپ اینستاگرام تست خود تأیید کنید (Settings and activity ← Apps and websites).
3. 3در پنل ویجنت، دکمه اتصال را بزنید — مستقیم به Instagram Login می‌روید و فرآیند OAuth را طی می‌کنید.
4. 4یک پیام تست بفرستید و در پنل ویجنت ببینید.

۱۳. ویدئوهای آموزشی

این ویدئوها برای درک بهتر فرآیند راه‌اندازی مفید هستند:

• Instagram Graph API | Setup Tutorial — https://www.youtube.com/watch?v=BuF9g9_QC04
• Get started with the Messenger API for Instagram — https://www.youtube.com/watch?v=Pi2KxYeGMXo
• Connect Meta Graph API (Facebook/Instagram) To n8n — https://www.youtube.com/watch?v=6XAErS9Q0oY