<div dir="rtl">

# 💬 دایرکت و کامنت هوشمند اینستاگرام — نسخه 2.0

ورکفلوی **n8n** که با **API رسمی متا** به دایرکت‌ها و کامنت‌های پیج اینستاگرام شما با هوش مصنوعی **Gemini** جواب می‌دهد.

طراحی و آموزش: **مرتضی عظیمی** — [mortezaazimi.ir](https://mortezaazimi.ir)

## ✨ قابلیت‌ها

- 💬 **جواب هوشمند دایرکت** با حافظه‌ی گفتگو (۱۰ پیام آخر هر کاربر)
- 📝 **کامنت → دایرکت:** یک جواب کوتاه عمومی زیر کامنت + جواب کامل در دایرکت کامنت‌گذار
- 🔑 **کلمه‌ی کلیدی:** هر کس «قیمت» (یا هر کلمه‌ای که تعریف کنید) بنویسد، پیام آماده‌ی شما برایش می‌رود
- 🖼 پیام ثابت برای عکس، ویس و استیکر
- 🛟 پیام پشتیبان وقتی هوش مصنوعی خطا بدهد
- ✅ **بدون جواب تکراری:** پاسخ فوری 200 به متا + حذف رویدادهای تکراری
- 🚫 به پیام‌ها و کامنت‌های خود پیج، «دیده شد» و ری‌اکشن جواب نمی‌دهد
- 🔒 بررسی Verify Token هنگام اتصال وبهوک
- ⚙️ همه‌ی تنظیمات در **یک گره**؛ آی‌دی پیج خودکار تشخیص داده می‌شود

## 🧭 مسیر کار

```
وبهوک متا → ⚙️ Settings → Is Verification?
   ├─ GET  → Verify Webhook (چک Verify Token)
   └─ POST → Ack 200 → Normalize Events → Needs AI?
                 ├─ بله → AI Agent (+ Gemini + Memory) ─┐
                 └─ نه (کلمه‌ی کلیدی/رسانه) ────────────┴→ Build Replies
                                                            ├─ Send DM
                                                            └─ Public Reply
```

---

## ✅ پیش‌نیازها

1. **n8n** با آدرس **HTTPS عمومی** (سرور خارج از ایران)
2. پیج اینستاگرام از نوع **Business** یا **Creator**
3. حساب [Meta for Developers](https://developers.facebook.com)
4. کلید رایگان **Gemini** از [aistudio.google.com/apikey](https://aistudio.google.com/apikey)

## 🚀 راه‌اندازی

### ۱. Import و تنظیمات
- در n8n: **Workflows ← Import from File** ← `Instagram-AI-Inbox.json`
- گره **⚙️ Settings** را پر کنید؛ مهم‌تر از همه `businessInfo` (اطلاعات کسب‌وکار) و `verifyToken` (یک رمز دلخواه)
- ورکفلو را **Active** کنید و **Production URL** گره **Instagram Webhook** را کپی کنید

### ۲. ساخت اپ متا
1. در developers.facebook.com ← **My Apps ← Create App** ← نوع **Business**
2. محصول **Instagram** را اضافه کنید ← **API setup with Instagram login**
3. پیج اینستاگرام را اضافه کنید و **Generate token** را بزنید؛ توکن را کپی کنید
4. در بخش **Configure webhooks**:
   - Callback URL = آدرس Production وبهوک n8n
   - Verify token = همان `verifyToken` تنظیمات
   - **Verify and save** را بزنید
   - فیلدهای **messages** و **comments** را Subscribe کنید

### ۳. اجازه‌ی دسترسی در اینستاگرام
در اپ اینستاگرام: **Settings ← Messages and story replies ← Message controls ← Connected tools ← Allow access to messages** را روشن کنید.

### ۴. اعتبارنامه‌ها در n8n

| اعتبارنامه | گره | مقدار |
|---|---|---|
| **Header Auth** «Instagram Token» | Send DM و Public Reply | Name: `Authorization` · Value: `Bearer توکن_اینستاگرام` |
| **Google Gemini (PaLM) API** | Gemini Chat Model | کلید Gemini |

### ۵. تست
از یک حساب دیگر به پیج دایرکت بدهید و زیر یک پست کامنت بگذارید.

> ⚠️ **حالت Development:** تا وقتی اپ در حالت Development است، فقط حساب‌هایی که در اپ نقش دارند (Admin/Tester) جواب می‌گیرند. برای جواب به همه‌ی مشتری‌ها باید اپ را **Live** کنید و دسترسی **Advanced** برای `instagram_business_manage_messages` و `instagram_business_manage_comments` را از **App Review** بگیرید.

---

## 🎛 تنظیمات (گره ⚙️ Settings)

| فیلد | توضیح |
|---|---|
| `verifyToken` | رمز تأیید وبهوک؛ باید با پنل متا یکی باشد |
| `replyToDMs` / `replyToComments` | روشن/خاموش جواب به دایرکت / کامنت |
| `commentMode` | `both` (پیش‌فرض): جواب کوتاه عمومی + جواب کامل دایرکت · `dm`: فقط دایرکت · `public`: فقط جواب عمومی |
| `publicReplyText` | متن جواب عمومی؛ `{username}` با آیدی کامنت‌گذار جایگزین می‌شود |
| `keywords` | هر خط یک قانون: `کلمه | پاسخ` (در دایرکت و کامنت) |
| `mediaReplyText` | جواب به عکس، ویس و استیکر |
| `fallbackText` | پیام پشتیبان وقتی هوش مصنوعی خطا بدهد |
| `businessInfo` | اطلاعات کسب‌وکار که هوش مصنوعی از آن جواب می‌دهد |

## 📏 قوانین متا که باید بدانید

- در دایرکت فقط تا **۲۴ ساعت** بعد از آخرین پیام مشتری می‌توانید جواب بدهید.
- به هر کامنت فقط **یک پیام خصوصی** می‌شود فرستاد، تا **۷ روز** بعد از کامنت.
- متن دایرکت حداکثر **۱۰۰۰ کاراکتر** است (ورکفلو خودکار کوتاهش می‌کند).
- توکن اینستاگرام حدود **۶۰ روز** اعتبار دارد؛ قبل از انقضا آن را تمدید و در اعتبارنامه جایگزین کنید.

## 🛠 عیب‌یابی

| مشکل | راه‌حل |
|---|---|
| Verify and save خطا می‌دهد | ورکفلو Active نیست، آدرس Production نیست، یا Verify Token با تنظیمات یکی نیست. |
| هیچ رویدادی نمی‌رسد | فیلدهای messages و comments را Subscribe نکرده‌اید، یا «Allow access to messages» خاموش است. |
| فقط به حساب خودم جواب می‌دهد | اپ در حالت Development است؛ بخش «حالت Development» بالا را ببینید. |
| خطای 190 یا 401 در Send DM | توکن منقضی یا اشتباه است؛ مقدار باید با `Bearer ` شروع شود. |
| خطای «outside of allowed window» | بیش از ۲۴ ساعت از پیام مشتری گذشته است. |
| به یک کامنت دایرکت نرفت | به آن کامنت قبلاً پیام خصوصی فرستاده شده یا بیش از ۷ روز گذشته است. |

## ⚠️ تغییرات نسبت به نسخه‌ی قبل

- پاسخ فوری به متا اضافه شد (رفع جواب‌های تکراری)
- رویدادهای «دیده شد»، ری‌اکشن و پیام‌های غیرمتنی دیگر به هوش مصنوعی نمی‌روند
- شاخه‌ی جداافتاده‌ی «کامنت در دایرکت» به قابلیت کامل **کامنت → دایرکت** تبدیل شد
- پرامپتی که در Notes بود (و به مدل نمی‌رسید) به پرامپت واقعی تبدیل شد
- آی‌دی و یوزرنیم ثابت حذف شد؛ پیج خودکار تشخیص داده می‌شود
- ۳ هوش مصنوعی جدا به یک مغز مشترک با حافظه تبدیل شد
- متن ارسالی با `JSON.stringify` ساخته می‌شود؛ هیچ کاراکتری ارسال را خراب نمی‌کند

</div>