<div dir="rtl">

# 🤖 دستیار هوشمند تلگرام با Gemini — نسخه 2.0 (ربات + Business)

ورکفلوی آماده‌ی **n8n** که در تلگرام به مشتری‌های شما جواب می‌دهد؛ هم از طریق **ربات** و هم مستقیم از **حساب شخصی شما** (Telegram Business).

## 🆕 تازه‌های نسخه ۲

- 👤 **Telegram Business:** دستیار از طرف حساب شخصی شما در پی‌وی جواب می‌دهد
- 🤫 **«خودم جواب دادم»:** اگر در یک چت Business دستی جواب بدهید، دستیار برای همان چت ساکت می‌ماند (پیش‌فرض ۳۰ دقیقه)
- ✨ **رفع کامل مشکل HTML:** بولد، ایتالیک، لینک قابل کلیک، فهرست، نقل‌قول، کد، تیتر و جدول درست نمایش داده می‌شوند
- 🛟 اگر تلگرام قالب HTML را نپذیرد، پیام **خودکار به‌صورت متن ساده** ارسال می‌شود؛ مشتری هیچ‌وقت بی‌جواب نمی‌ماند
- ✂️ پیام‌های بلندتر از سقف تلگرام روی پاراگراف‌ها **تکه‌تکه** و به‌ترتیب ارسال می‌شوند
- 🚫 ویرایش پیام، اتصال حساب و رویدادهای دیگر نادیده گرفته می‌شوند (دیگر خطا نمی‌دهد)

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

- 💬 پیام **متنی**، 🎤 **ویس** و 🖼 **عکس** را می‌فهمد
- 🔊 به ویس **با صدای طبیعی** (Gemini TTS) جواب می‌دهد
- ⌨️ «در حال نوشتن…» / «در حال ضبط صدا…» (در Business هم)
- ↩️ جواب روی پیام مشتری **Reply** می‌شود
- 👋 خوش‌آمد **‎/start** (حالت ربات)
- 🧠 **حافظه‌ی گفتگو:** ۱۰ پیام آخر هر مشتری
- 👥 در **گروه‌ها ساکت** می‌ماند
- ☁️ **بدون ffmpeg**؛ روی n8n Cloud و نسخه‌ی خودمیزبان
- 📝 کنار هر بخش یک **یادداشت راهنمای فارسی**

## 📦 محتویات بسته

| فایل | توضیح |
|---|---|
| `Telegram-AI-Assistant-v2.json` | فایل ورکفلو برای Import در n8n (۲۲ گره + ۷ یادداشت) |
| `README.md` | همین راهنما |

## 🧭 مسیر کار ورکفلو

```
پیام تلگرام → ⚙️ Settings → Normalize Update
   (ربات یا Business؟ پیام خود شما؟ گروه؟ ویرایش؟ چت در حالت سکوت؟)
   ├─ /start → خوش‌آمد
   ├─ متن ──────────────────────────────────┐   (هم‌زمان: «در حال نوشتن…»)
   ├─ ویس/عکس → دریافت فایل → Gemini (تحلیل) ┤→ آماده‌سازی → AI Agent (+حافظه)
   └─ سایر → «پشتیبانی نمی‌شود»               │
                                              ├─ ویس بود → Gemini TTS → MP3 → ارسال صوت
                                              └─ متن → Markdown→HTML → ارسال
                                                          (خطای HTML → متن ساده)
```

---

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

1. **n8n** با آدرس **HTTPS عمومی**. وبهوک تلگرام روی localhost کار نمی‌کند.
2. **یک ربات تلگرام** از ‎@BotFather.
3. **کلید API جمنای** از [Google AI Studio](https://aistudio.google.com/apikey). ردیف رایگان دارد.
4. برای حالت Business: **Telegram Premium** (اختیاری).

> ⚠️ **نکته برای کاربران ایران:** Bot API تلگرام و Gemini از IP ایران در دسترس نیستند. سرور n8n باید خارج از ایران باشد.

---

## 🚀 راه‌اندازی قدم‌به‌قدم

### قدم ۱ — ساخت ربات در BotFather

1. به [‎@BotFather](https://t.me/BotFather) پیام بدهید و `/newbot` را بفرستید.
2. نام و نام کاربری (ختم به `bot`) بدهید.
3. **توکن** را کپی کنید: `123456789:AA...`

### قدم ۲ — گرفتن کلید Gemini

[aistudio.google.com/apikey](https://aistudio.google.com/apikey) ← **Create API key** ← کلید را کپی کنید.

### قدم ۳ — Import ورکفلو

در n8n: **Workflows ← Import from File** ← `Telegram-AI-Assistant-v2.json`.

### قدم ۴ — اعتبارنامه‌ها و تنظیمات

| کجا | چه چیزی |
|---|---|
| **Telegram API** (گره‌های Telegram Trigger و Get File) | Access Token = توکن ربات |
| **Header Auth** «Gemini API Key» (گره‌های Gemini – Transcribe / Describe و Gemini TTS) | Name: `x-goog-api-key` / Value: کلید جمنای |
| **Google Gemini (PaLM) API** (گره Gemini Chat Model) | API Key = کلید جمنای |
| گره **⚙️ Settings** | `botToken` = همان توکن ربات · `silenceMinutes` = مدت سکوت (۳۰ پیش‌فرض، ۰ = خاموش) |

> چرا توکن دو جا؟ گره رسمی تلگرام در n8n از `business_connection_id` پشتیبانی نمی‌کند، پس همه‌ی ارسال‌ها با HTTP Request به Bot API انجام می‌شوند و توکن را از Settings می‌خوانند.

### قدم ۵ — اتصال به حساب شخصی (اختیاری، Telegram Business)

1. در ‎@BotFather: `/mybots` ← ربات ← **Bot Settings ← Business Mode ← Turn on**
2. در تلگرام خودتان: **Settings ← Telegram Business ← Chatbots**
3. یوزرنیم ربات را وارد کنید و **Reply to messages** را روشن کنید.
4. مشخص کنید دستیار به کدام چت‌ها دسترسی داشته باشد.

### قدم ۶ — شخصی‌سازی پرامپت

در گره **AI Agent**، خط آخر System Message را با اطلاعات کسب‌وکارتان جایگزین کنید: خدمات، قیمت‌ها، ساعت کاری، آدرس، لینک سایت و راه‌های تماس.

### قدم ۷ — فعال‌سازی و تست

1. ورکفلو را **Active** کنید.
2. حالت ربات: به ربات Start بدهید و متن، ویس، عکس و استیکر را تست کنید.
3. حالت Business: از یک حساب دیگر به پی‌وی خودتان پیام بدهید. بعد خودتان دستی جواب بدهید و ببینید دستیار ساکت می‌شود.

---

## 🎛 شخصی‌سازی

| چه چیزی | کجا | چطور |
|---|---|---|
| مدت سکوت بعد از جواب دستی | **⚙️ Settings** | `silenceMinutes` (۰ = خاموش) |
| صدای گوینده | **Gemini TTS** ← بدنه | `voice: 'Kore'` ← `Puck`، `Charon`، `Leda`… |
| لحن گفتار | **Gemini TTS** ← بدنه | فیلد `style` |
| کیفیت جواب‌ها | **Gemini Chat Model** | `gemini-3.5-flash-lite` ← `gemini-3.8-flash` |
| پیام خوش‌آمد / پشتیبانی‌نشده | **Send Welcome** / **Send Unsupported** | متن داخل بدنه (`text`) |
| جواب دادن در گروه‌ها | **Normalize Update** | خط «گروه و کانال» را حذف کنید |
| حافظه‌ی دائمی | **Memory** | جایگزینی با Postgres یا Redis Chat Memory |

---

## 🛠 عیب‌یابی

| مشکل | علت و راه‌حل |
|---|---|
| هیچ جوابی نمی‌آید | ورکفلو Active نیست، n8n آدرس HTTPS عمومی ندارد (`WEBHOOK_URL`) یا توکن در ⚙️ Settings وارد نشده. هر ربات فقط یک وبهوک دارد. |
| خطای 401 یا 404 در گره‌های ارسال | `botToken` در Settings اشتباه یا خالی است. |
| در Business جواب نمی‌دهد | Business Mode در BotFather روشن نیست، گزینه‌ی Reply to messages خاموش است، آن چت در فهرست دسترسی ربات نیست، یا به‌تازگی خودتان در آن چت جواب داده‌اید (حالت سکوت). |
| بولد یا لینک نمایش داده نمی‌شود | پرامپت باید از هوش مصنوعی بخواهد لینک را به شکل `[متن](آدرس)` بنویسد. اگر تلگرام قالب را رد کند، متن ساده می‌رود؛ خطای گره Send Text را در Executions ببینید. |
| سکوت بعد از جواب دستی کار نمی‌کند | حافظه‌ی سکوت فقط در اجرای Active (نه دکمه‌ی Test) ذخیره می‌شود. |
| بعد از تست دستی، ربات از کار افتاد | ورکفلو را Deactivate و دوباره Activate کنید. |
| خطای 400/403 در گره‌های Gemini | کلید یا نام Header اشتباه است، یا سرور در منطقه‌ی تحریم‌شده است. |
| model not found | نام مدل جدید را از [صفحه‌ی مدل‌ها](https://ai.google.dev/gemini-api/docs/models) بردارید. |

---

## 👤 سازنده

طراحی و آموزش: **مرتضی عظیمی**

🌐 [mortezaazimi.ir](https://mortezaazimi.ir) · 📢 [تلگرام](https://t.me/mortezaazimi75) · 📸 [اینستاگرام](https://www.instagram.com/mortezaazimi.ir/)

## ⚖️ اجزای جانبی

گره **WAV → MP3** نسخه‌ی کامل کتابخانه‌ی متن‌باز [lamejs](https://github.com/zhuker/lamejs) را بدون تغییر در خود دارد (مجوز **LGPL-3.0**).

</div>