آموزش اتصال اینستاگرام به Meta Graph API و راه‌اندازی Webhook برای کامنت و دایرکت

قرار است دقیقاً چه چیزی بسازیم؟

هدف این آموزش اتصال مستقیم Instagram به API رسمی Meta است؛ یعنی بدون سرویس واسط بتوانیم اتفاق‌هایی مثل ثبت یک کامنت یا دریافت یک Direct Message را روی سرور خودمان دریافت کنیم و بعد بر اساس آن منطق دلخواه اجرا کنیم.

معماری کلی به این شکل است:

1. کاربر روی Instagram یک کامنت یا پیام ایجاد می‌کند.
2. Meta از طریق Webhook سرور ما را مطلع می‌کند.
3. سرور Payload رویداد را بررسی می‌کند.
4. منطق برنامه، مثلاً بررسی کلمه کلیدی، اجرا می‌شود.
5. در صورت نیاز با Instagram API درخواست دیگری برای پاسخ به کامنت یا ارسال پیام ارسال می‌کنیم.

این آموزش از کدام روش Instagram API استفاده می‌کند؟

Meta در حال حاضر دو روش اصلی برای اتصال حساب‌های Professional ارائه می‌کند: Instagram API with Instagram Login و Instagram API with Facebook Login. در روش Instagram Login الزاماً نیازی به اتصال Facebook Page نیست؛ اما در این آموزش عمداً از Instagram API with Facebook Login استفاده می‌کنیم، چون می‌خواهیم Facebook Account، Facebook Page و Instagram Professional Account را در یک ساختار متصل داشته باشیم.

پیش‌نیازها

قبل از ورود به پنل Developer این موارد را آماده کنید:

• یک حساب واقعی Facebook.
• یک Instagram Account از نوع Business یا Creator.
• یک Facebook Page.
• اتصال Instagram Professional Account به همان Facebook Page.
• دسترسی مدیریتی مناسب روی Facebook Page.
• یک سرور عمومی با HTTPS.
• یک دامنه یا Subdomain مانند api.example.com.
• امکان نگهداری امن App Secret و Access Token در Backend.

مرحله اول: تبدیل Instagram به Professional Account

اگر حساب شما هنوز Personal است ابتدا وارد تنظیمات Instagram شوید و آن را به Professional تبدیل کنید. بسته به نسخه اپلیکیشن، عنوان منو ممکن است کمی متفاوت باشد، اما معمولاً از بخش Settings → Account type and tools → Switch to professional account می‌توانید یکی از حالت‌های Creator یا Business را انتخاب کنید.

برای کار با API در سناریوی این مقاله هر دو حالت Business و Creator قابل استفاده هستند.جای تصویر ۲ — تبدیل حساب Instagram به Professional
اسکرین‌شات Account type and tools

مرحله دوم: اتصال Instagram به Facebook Page

در روش Facebook Login، صرفاً Professional بودن Instagram کافی نیست و باید آن را به یک Facebook Page متصل کنید. می‌توانید این کار را از تنظیمات Professional Account در Instagram یا از تنظیمات Facebook Page و بخش Linked Accounts انجام دهید.

نکته مهم این است که Facebook Accountای که بعداً با آن Access Token می‌گیرید باید روی همان Page دسترسی لازم را داشته باشد.

مرحله سوم: ثبت‌نام در Meta for Developers

حالا باید Facebook Account خود را به Developer Account تبدیل کنید. لینک مستقیم ثبت‌نام:

https://developers.facebook.com/async/registration/

با همان Facebook Accountای وارد شوید که به Facebook Page موردنظر دسترسی دارد. Meta ممکن است در جریان ثبت‌نام یا استفاده از Developer Platform بررسی‌های امنیتی یا تأیید هویت حساب را درخواست کند.

مرحله چهارم: ساخت Meta App

بعد از ورود به Meta for Developers وارد My Apps شوید و گزینه Create App را بزنید.

رابط Meta طی سال‌های اخیر چند بار تغییر کرده و بسیاری از آموزش‌های قدیمی هنوز مسیر Add Products → Instagram Graph API را نشان می‌دهند. در نسخه‌های جدید Dashboard بیشتر قابلیت‌ها بر اساس Use case مدیریت می‌شوند.

برای این سناریو در بخش Use cases به دنبال گزینه‌ای با عنوانی مشابه Manage messaging & content on Instagram باشید. سپس وارد Customize شوید و روش API setup with Facebook Login را انتخاب کنید.

مرحله پنجم: App ID و App Secret را بردارید

از مسیر App settings → Basic می‌توانید App ID و App Secret را مشاهده کنید.

App ID محرمانه محسوب نمی‌شود، اما App Secret باید فقط در Backend نگهداری شود. پیشنهاد می‌کنم مقادیر را در Environment Variable قرار دهید:

META_APP_ID=YOUR_APP_ID
META_APP_SECRET=YOUR_APP_SECRET
META_WEBHOOK_VERIFY_TOKEN=YOUR_RANDOM_SECRET

META_WEBHOOK_VERIFY_TOKEN را خودتان می‌سازید. این مقدار با Access Token فرق دارد و فقط برای handshake اولیه Webhook استفاده می‌شود.

مرحله ششم: Permissionهای لازم را فعال کنید

در App Dashboard وارد Use case مربوط به Instagram شوید و بخش Permissions and features را باز کنید. در بعضی نسخه‌های پنل همین موارد از مسیر App Review → Permissions and Features دیده می‌شوند.

برای سناریوی دریافت کامنت و دایرکت با Facebook Login معمولاً این Permissionها اهمیت دارند:

• instagram_basic — دسترسی پایه به Instagram Professional Account.
• instagram_manage_comments — خواندن و مدیریت کامنت‌ها و پاسخ دادن به آن‌ها.
• instagram_manage_messages — کار با Instagram Messaging.
• pages_show_list — پیدا کردن Facebook Pageهایی که کاربر مدیریت می‌کند.
• pages_read_engagement — برای بخش‌هایی از دسترسی مربوط به Page و Instagram Comment Management.
• pages_manage_metadata — برای قابلیت‌های مرتبط با Webhook و Messaging در روش Facebook Login.

اگر در آینده قصد انتشار پست و Reel را هم دارید، instagram_content_publish را نیز اضافه کنید؛ اما برای آموزش دریافت کامنت و پیام، آن را بی‌دلیل درخواست نکنید.

مرحله هفتم: Access Token بگیرید

برای تست روی اکانت خودتان ساده‌ترین ابزار، Graph API Explorer است:

Graph API Explorer

Meta App خودتان را از لیست انتخاب کنید و یک User Access Token با Permissionهای موردنیاز ایجاد کنید.

برای این آموزش حداقل Permissionهای مرتبط با قابلیت‌هایی که فعال کرده‌اید را انتخاب کنید؛ برای مثال:

pages_show_list
pages_read_engagement
pages_manage_metadata
instagram_basic
instagram_manage_comments
instagram_manage_messages

Short-lived Token را برای Production استفاده نکنید

توکنی که برای تست می‌گیرید ممکن است موقتی باشد. در یک پیاده‌سازی واقعی باید OAuth Flow و مدیریت چرخه عمر Token را انجام دهید. در Facebook Login امکان exchange کردن User Token کوتاه‌مدت به Long-lived User Token وجود دارد.

GET https://graph.facebook.com/v26.0/oauth/access_token
    ?grant_type=fb_exchange_token
    &client_id=APP_ID
    &client_secret=APP_SECRET
    &fb_exchange_token=SHORT_LIVED_USER_TOKEN

این درخواست را فقط از Backend اجرا کنید چون App Secret در آن استفاده می‌شود.

منظور از Validate یا Revalidate کردن Token چیست؟

اصطلاح Revalidate یک مرحله جادویی جداگانه در Instagram نیست. شما باید وضعیت Token، Permissionها، تاریخ انقضا و اعتبار آن را بررسی کنید و در صورت invalid شدن، دوباره authorization انجام دهید. ابزار رسمی Meta برای این کار Access Token Debugger است:

https://developers.facebook.com/tools/debug/accesstoken/

مرحله هشتم: Page Access Token و Instagram User ID را پیدا کنید

در روش Facebook Login معمولاً User Access Token را برای پیدا کردن Pageهای تحت مدیریت کاربر استفاده می‌کنیم:

GET https://graph.facebook.com/v26.0/me/accounts?fields=name,access_token,tasks,instagram_business_account&access_token=USER_ACCESS_TOKEN

سه مقدار مهم را نگه دارید:

• PAGE_ID
• PAGE_ACCESS_TOKEN
• IG_USER_ID یا همان مقدار instagram_business_account.id

اگر instagram_business_account در پاسخ وجود ندارد، معمولاً باید اول اتصال Instagram Professional Account به Facebook Page را بررسی کنید.

مرحله نهم: سرور Webhook را بسازید

Webhook باید یک URL عمومی مانند نمونه زیر داشته باشد:

https://api.example.com/webhooks/meta/instagram

localhost برای دریافت Webhook واقعی کافی نیست، مگر اینکه در محیط توسعه با یک Tunnel آن را به یک URL عمومی HTTPS تبدیل کنید.

مرحله Verification

وقتی Callback URL را در Meta ثبت می‌کنید، Meta ابتدا یک درخواست GET به سرور شما می‌فرستد. پارامترهای اصلی آن شامل این موارد هستند:

hub.mode
hub.verify_token
hub.challenge

سرور باید بررسی کند که hub.verify_token با Verify Token خودتان برابر باشد و سپس مقدار hub.challenge را به Meta برگرداند.

یک نمونه ساده با Express:

app.get('/webhooks/meta/instagram', (req, res) => {
  const mode = req.query['hub.mode'];
  const token = req.query['hub.verify_token'];
  const challenge = req.query['hub.challenge'];

  if (mode === 'subscribe' && token === process.env.META_WEBHOOK_VERIFY_TOKEN) {
    return res.status(200).send(challenge);
  }

  return res.sendStatus(403);
});

توجه کنید Verify Token را Meta تولید نمی‌کند؛ شما خودتان یک رشته امن تعریف می‌کنید و همان مقدار را هم در Backend و هم در تنظیمات Webhook وارد می‌کنید.

دریافت Eventها با POST

app.post('/webhooks/meta/instagram', (req, res) => {
  console.log(req.body);
  res.sendStatus(200);
});

مرحله دهم: Webhook را داخل Meta ثبت کنید

در Meta App Dashboard وارد بخش Webhooks مربوط به Instagram شوید. بسته به نسخه Dashboard ممکن است این بخش مستقیماً با عنوان Webhooks یا داخل Use case مربوط به Instagram نمایش داده شود.

دو مقدار وارد می‌کنید:

• Callback URL: مثلاً https://api.example.com/webhooks/meta/instagram
• Verify Token: همان مقدار META_WEBHOOK_VERIFY_TOKEN

بعد از زدن Verify and Save، Meta درخواست GET مرحله قبل را به سرور شما می‌فرستد. اگر Challenge صحیح برگردد، Callback تأیید می‌شود.

مرحله یازدهم: مشخص کنید چه Eventهایی را می‌خواهید

صرف ثبت Callback URL به این معنی نیست که تمام اتفاق‌های Instagram برای شما ارسال می‌شوند. باید Fieldهای موردنیاز را Subscribe کنید.

برای پروژه‌ای شبیه دایرکت هوشمند این موارد معمولاً مهم هستند:

• comments — کامنت‌های جدید روی Media.
• messages — دریافت پیام‌های Instagram.
• messaging_postbacks — رویدادهای مربوط به Postbackها و بعضی تعاملات Messaging.
• message_reactions — اگر Reaction پیام برای شما اهمیت دارد.
• live_comments — فقط اگر کامنت Instagram Live را لازم دارید.

مرحله دوازدهم: Instagram Account را به App Subscribe کنید

این یکی از قسمت‌هایی است که زیاد فراموش می‌شود. داشتن Callback URL معتبر لزوماً به این معنی نیست که اکانت Instagram موردنظر برای تمام Eventها به App شما Subscribe شده است.

POST https://graph.facebook.com/v26.0/IG_USER_ID/subscribed_apps
  ?subscribed_fields=comments
  &access_token=PAGE_ACCESS_TOKEN

برای بررسی Subscription موجود:

GET https://graph.facebook.com/v26.0/IG_USER_ID/subscribed_apps
  ?access_token=PAGE_ACCESS_TOKEN

مرحله سیزدهم: یک کامنت واقعی تست کنید

حالا از یک اکانت دیگر روی یکی از پست‌های Instagram کامنت بگذارید و Log سرور را ببینید.

{
  "object": "instagram",
  "entry": [
    {
      "id": "IG_USER_ID",
      "changes": [
        {
          "field": "comments",
          "value": {
            "id": "COMMENT_ID",
            "text": "webhook"
          }
        }
      ]
    }
  ]
}

از اینجا به بعد منطق اختصاصی برنامه شما شروع می‌شود.

if (comment.text.trim().toLowerCase() === 'webhook') {
  // reply to comment
  // or send a supported private reply
}

پاسخ دادن به کامنت

POST https://graph.facebook.com/v26.0/IG_COMMENT_ID/replies

message=ممنون، آموزش برات ارسال شد
access_token=PAGE_ACCESS_TOKEN

آیا بعد از کامنت می‌توانیم مستقیم DM بفرستیم؟

اینجا باید بین دو قابلیت تفاوت قائل شویم. Send API معمولی اجازه نمی‌دهد هر زمان خواستید یک گفت‌وگوی جدید و بدون Context با هر کاربر Instagram شروع کنید؛ در Messaging معمولاً کاربر باید ابتدا با Professional Account تعامل Messaging داشته باشد.

اما سناریوی معروف «کلمه X را کامنت کن تا لینک در دایرکت برایت ارسال شود» از جریان مخصوص Private Reply to Comment استفاده می‌کند که پیام را به همان Comment مرتبط می‌کند. بنابراین اگر هدفتان دقیقاً ساخت اتوماسیون Comment-to-DM است، نباید آن را با ارسال آزاد یک Direct Message معمولی اشتباه بگیرید.

Development Mode و App Review

تا زمانی که App در محیط Development و با Standard Access است، معمولاً برای تست روی Accountها و Assetهایی که متعلق به خودتان هستند یا به‌عنوان App Role/Test User تعریف شده‌اند مشکلی ندارید.

اما اگر قرار است یک سرویس عمومی بسازید و کاربران دیگر Instagram خودشان را به اپ شما متصل کنند، باید سراغ Advanced Access، App Review و در قابلیت‌های مربوطه Business Verification بروید.

نسخه Graph API را فراموش نکنید

در زمان نگارش این مطلب در سپتامبر ۲۰۲۶، جدیدترین نسخه منتشرشده Graph API نسخه v26.0 است. Meta نسخه‌های API را به‌مرور بازنشسته می‌کند؛ بنابراین قبل از استفاده، Changelog رسمی را بررسی کنید.

چک‌لیست نهایی

• Instagram Account از نوع Business یا Creator است.
• Instagram به Facebook Page متصل شده است.
• Facebook Account روی Page دسترسی کافی دارد.
• Developer Account ساخته شده است.
• Meta App ایجاد شده است.
• Use case مربوط به Instagram با Facebook Login تنظیم شده است.
• Permissionهای موردنیاز اضافه شده‌اند.
• User Access Token گرفته شده است.
• Page Access Token و IG User ID پیدا شده‌اند.
• توکن با Access Token Debugger بررسی شده است.
• Webhook روی یک URL عمومی HTTPS قرار دارد.
• Callback URL توسط Meta Verify شده است.
• Fieldهای comments و در صورت نیاز Messaging Subscribe شده‌اند.
• Subscription واقعی Instagram Account بررسی شده است.
• در Production امضای X-Hub-Signature-256 بررسی می‌شود.
• Token و App Secret هرگز به Front-end ارسال نمی‌شوند.
• برای اتصال کاربران خارج از App Roles، App Review و Advanced Access بررسی شده است.

جمع‌بندی

برای ساخت سیستمی شبیه سرویس‌های دایرکت هوشمند نیازی نیست دائماً Instagram را Poll کنید. Instagram می‌تواند Eventهای موردنیاز را از طریق Webhook به Backend شما ارسال کند. کاری که باید انجام دهید این است که حساب Professional را به ساختار Meta متصل کنید، Permission صحیح بگیرید، Tokenها را به‌درستی مدیریت کنید و یک Webhook امن و عمومی داشته باشید.

بعد از این مرحله، بخش جذاب پروژه شروع می‌شود: ذخیره Ruleها در دیتابیس، تشخیص Keyword، جلوگیری از پاسخ تکراری، Queue کردن Eventها، Reply به Comment و در نهایت پیاده‌سازی جریان Comment-to-DM با API رسمی Meta.