<div dir="rtl">

# 🤖 دستیار هوشمند بله با Gemini — نسخه 1.0

ورکفلوی آماده‌ی **n8n** که ربات شما در پیام‌رسان **بله** را به یک دستیار فروش و پشتیبانی هوشمند فارسی‌زبان تبدیل می‌کند.

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

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

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

| فایل | توضیح |
|---|---|
| `Bale-AI-Assistant.json` | فایل ورکفلو برای Import در n8n |
| `README.md` | همین راهنما |

## 🧩 چطور با بله کار می‌کند؟

API ربات بله با **Bot API تلگرام سازگار** است. برای همین گره‌های ارسال و دریافت فایل همان **گره تلگرام n8n** هستند که آدرس پایه‌شان به `https://tapi.bale.ai` تغییر کرده است.

یک تفاوت مهم هست: بله هدر امنیتی‌ای که گره Telegram Trigger لازم دارد را نمی‌فرستد. برای همین پیام‌ها با یک گره **Webhook** معمولی دریافت می‌شوند و آدرس وبهوک **یک بار به‌صورت دستی** در بله ثبت می‌شود (قدم ۶).

```
پیام بله → Webhook → تشخیص نوع
  ├─ گروه/کانال → نادیده
  ├─ /start → پیام خوش‌آمد
  ├─ متن ───────────────────────────────────┐
  ├─ ویس/عکس → دریافت فایل → Gemini (تحلیل) ┤→ آماده‌سازی → AI Agent (+حافظه)
  └─ سایر → «پشتیبانی نمی‌شود»                │
                                             ├─ پیام ویس بود → Gemini TTS → MP3 → ارسال صوت
                                             └─ در غیر این صورت → ارسال متن
```

---

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

1. **n8n** با آدرس **HTTPS عمومی روی پورت 443**. بله فقط پورت‌های 443 و 88 را برای وبهوک قبول می‌کند.
2. **یک ربات بله** که از بات‌فادر می‌سازید.
3. **کلید API جمنای** از [Google AI Studio](https://aistudio.google.com/apikey).

> ⚠️ **نکته‌ی مهم درباره‌ی محل سرور:** Gemini از IP ایران در دسترس نیست، پس سرور n8n باید خارج از ایران باشد. بعد از ساخت اعتبارنامه‌ی بله، دکمه‌ی تست اتصال را بزنید تا مطمئن شوید سرور شما به `tapi.bale.ai` دسترسی دارد. اگر دسترسی نداشت، باید از سروری استفاده کنید که هم به بله و هم به Gemini دسترسی داشته باشد.

---

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

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

1. در بله به [‎@botfather](https://ble.ir/botfather) پیام بدهید و `/newbot` را بفرستید.
2. یک **نام** و یک **نام کاربری** که به `bot` ختم شود انتخاب کنید.
3. **توکن** ربات را کپی کنید.

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

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

### قدم ۳ — Import و تغییر Path وبهوک

1. در n8n: **Workflows ← Import from File** ← فایل `Bale-AI-Assistant.json`.
2. گره **Bale Webhook** را باز کنید و مقدار **Path** را به یک رشته‌ی تصادفی دلخواه عوض کنید، مثلاً `bale-k7x9q2m4p8`.

> 🔒 چون بله هدر امنیتی نمی‌فرستد، تنها چیزی که وبهوک شما را امن نگه می‌دارد محرمانه بودن آدرس آن است. این فایل عمومی منتشر شده، پس Path پیش‌فرض را حتماً عوض کنید.

### قدم ۴ — ساخت اعتبارنامه‌ها (Credentials)

| اعتبارنامه | گره‌ها | فیلدها |
|---|---|---|
| **Telegram API** (اسمش را بگذارید «Bale Bot») | Get File و همه‌ی Sendها | Access Token = توکن بله / **Base URL = `https://tapi.bale.ai`** |
| **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 = `کلید_جمنای` |

> 💡 اگر Base URL را عوض نکنید، n8n درخواست‌ها را به تلگرام می‌فرستد و ربات کار نمی‌کند.

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

در گره **AI Agent**، جای `[اینجا اطلاعات کسب‌وکار...]` اطلاعات کسب‌وکارتان را بنویسید.

### قدم ۶ — فعال‌سازی و ثبت وبهوک

1. ورکفلو را **Active** کنید.
2. در گره **Bale Webhook** تب **Production URL** را باز کنید و آدرس را کپی کنید.
3. این آدرس را در مرورگر باز کنید (توکن و آدرس را جایگزین کنید):

```
https://tapi.bale.ai/bot<TOKEN>/setWebhook?url=<PRODUCTION_URL>
```

باید پاسخی شبیه `{"ok":true,...}` ببینید. برای بررسی وضعیت:

```
https://tapi.bale.ai/bot<TOKEN>/getWebhookInfo
```

4. در بله ربات را باز کنید، **شروع** را بزنید و متن، ویس، عکس با کپشن و استیکر را تست کنید.

---

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

| چه چیزی | کجا | چطور |
|---|---|---|
| صدای گوینده | گره **Gemini TTS** ← بدنه | `voice: 'Kore'` را عوض کنید، مثلاً `Puck`، `Charon` یا `Leda` |
| لحن گفتار | گره **Gemini TTS** ← بدنه | فیلد `style` |
| مدل TTS ارزان‌تر | گره **Gemini TTS** | `gemini-3.8-flash-lite-tts` |
| کیفیت جواب‌ها | گره **Gemini Chat Model** | `gemini-3.8-flash` |
| پیام خوش‌آمد | گره **Send Welcome** | Text |
| جواب در گروه‌ها | گره **Route by Type** | خروجی Group را به Prepare Message وصل کنید |
| حافظه‌ی دائمی | گره **Memory** | Postgres یا Redis Chat Memory |

---

## 🛠 عیب‌یابی

| مشکل | علت و راه‌حل |
|---|---|
| ربات جواب نمی‌دهد | ورکفلو Active نیست، وبهوک ثبت نشده (قدم ۶) یا آدرس n8n روی پورت 443 نیست. با `getWebhookInfo` وضعیت را ببینید. |
| `setWebhook` خطا می‌دهد | آدرس باید HTTPS با گواهی معتبر و روی پورت 443 یا 88 باشد. |
| تست اعتبارنامه‌ی بله ناموفق است | توکن یا Base URL اشتباه است، یا سرور شما به `tapi.bale.ai` دسترسی ندارد. |
| خطای 400 یا 403 در گره‌های Gemini | کلید یا نام Header اشتباه است، یا سرور در منطقه‌ی تحریم‌شده است. |
| خطای مدل (model not found) | نام مدل جدید را از [صفحه‌ی مدل‌های Gemini](https://ai.google.dev/gemini-api/docs/models) بردارید. |
| به ویس، جواب متنی می‌آید | ساخت صدا خطا داده و مسیر پشتیبان فعال شده. خروجی Gemini TTS را در Executions ببینید. |
| بعد از تست دستی ربات از کار افتاد | آدرس Test با Production فرق دارد. دوباره `setWebhook` را با Production URL بزنید. |

---

## ℹ️ درباره‌ی پاسخ صوتی

`sendVoice` در بله فقط فایل `audio/ogg` قبول می‌کند و گره تلگرام n8n هم عملیات ارسال ویس ندارد. برای همین جواب صوتی به‌صورت **فایل صوتی MP3** با عنوان «پاسخ صوتی» ارسال می‌شود و داخل بله پخش می‌شود.

---

## 👤 سازنده

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

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

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

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

</div>