n8n-nodes-farazsms

نود رسمی فرازاس‌ام‌اس (Farazsms) برای n8n. با این نود می‌توانید بدون نوشتن حتی یک خط کد، در ورک‌فلوهای n8n پیامک بفرستید، پیام صوتی ارسال کنید و اعتبار حسابتان را استعلام بگیرید. این نود از طریق وب‌سرویس ایران‌پیامک (Iran Payamak) با سامانه ارتباط می‌گیرد.

The official Farazsms community node for n8n — send SMS, voice messages and check balance inside your automations, powered by the Iran Payamak web service. Bilingual (Persian/English) labels, zero trial-and-error setup.

✨ قابلیت‌ها | Features

🔔 نود Trigger — دریافت پیامک

نود Farazsms Trigger با رسیدن هر پیامک ورودی، ورک‌فلو را اجرا می‌کند — پایهٔ هر جریان دوطرفه (پاسخ خودکار، لغو اشتراک، نظرسنجی، فوروارد به تلگرام).

• فیلتر بر اساس خط گیرنده، شمارهٔ فرستنده و متن پیام
• هر پیام یک‌بار emit می‌شود (واترمارک روی شناسهٔ پیام). اگر بین دو بررسی حجم زیادی پیام برسد، نود صفحه‌به‌صفحه عقب می‌رود تا به پیام‌های دیده‌شده برسد — پس فقط صفحهٔ اول خوانده نمی‌شود.
• در فعال‌سازی، صندوق ورودی قدیمی بازپخش نمی‌شود (قابل تغییر با گزینهٔ Emit Backlog)

ℹ️ اجرای دستی «Fetch Test Event» عمداً واترمارک را جلو نمی‌برد، تا بتوانید بدون مصرف کردن صندوق تست کنید. یعنی پیام‌هایی که در تست دستی می‌بینید، بعداً یک‌بار دیگر توسط تریگر واقعی emit می‌شوند.

📤 نود اصلی

| Resource | Operation | کاربرد | |---|---|---| | پیامک | ارسال ساده / Send SMS | یک متن به یک یا چند گیرنده | | پیامک | ارسال پترن / Send Pattern | پیامک تراکنشی/OTP — می‌رسد در کمتر از ۵ ثانیه و صف نمی‌شود | | پیامک | ارسال شخصی‌سازی‌شده / Send Personalized | متن دارای %متغیر% با مقدار اختصاصی هر فرد | | پیامک | ارسال به بانک شماره / Send to Number Bank | کمپین هدفمند روی بانک شمارهٔ آماده، بدون دفترتلفن | | پیامک | ارسال کد پستی هدفمند / Send Targeted by Postal Code | فیلتر کد پستی، جنسیت، بازهٔ سنی، اپراتور و پیش‌شماره | | پیامک | تخمین تعداد گیرنده / Estimate Recipient Count | «چند نفر؟» — قبل از خرج کردن اعتبار | | پیامک | تخمین هزینه / Estimate Cost | «چقدر؟» — چیزی ارسال نمی‌شود و اعتبار کم نمی‌شود | | گزارش | فهرست ارسال‌ها / Get Send Requests | همهٔ ارسال‌ها با وضعیت کلی | | گزارش | وضعیت تحویل تک‌تک گیرندگان / Delivery Status Per Recipient | تحویل‌شده، ناموفق، بلک‌لیست — برای هر گیرنده | | گزارش | صندوق ورودی / Get Inbox | خواندن پیامک‌های دریافتی | | پترن | فهرست و جزئیات پترن / Get Patterns | وضعیت تأیید و نام دقیق متغیرها | | دفترتلفن | فهرست، مخاطبان، افزودن تکی و گروهی | همگام‌سازی مخاطب تا ۵۰۰ نفر در هر درخواست | | پیام صوتی | ارسال پیام صوتی / Send Voice | ارسال فایل صوتی آپلودشده | | حساب | استعلام اعتبار / Get Balance · فهرست خطوط / Get Sender Lines | موجودی، و خطوط قابل استفاده با تعرفه |

🎯 چیزهایی که کار را راحت می‌کنند

• فهرست کشویی پویا برای خط ارسال، کد پترن، بانک شماره و جنسیت — دیگر لازم نیست چیزی را دستی تایپ کنید
• مدیریت خودکار محدودیت نرخ — API سقف ۶۰ درخواست در دقیقه دارد؛ نود درخواست‌ها را خودش فاصله‌گذاری می‌کند تا ارسال انبوه وسط کار نشکند
• صفحه‌بندی خودکار — گزینهٔ Return All همهٔ صفحات را می‌آورد
• پیام خطای واقعی — به‌جای متن مبهم n8n، دقیقاً می‌گوید کدام فیلد مشکل دارد

🚀 نصب در ۳۰ ثانیه | Install

در n8n وارد مسیر زیر شوید و نام پکیج را وارد کنید:

Settings → Community Nodes → Install

@farazsms_official/n8n-nodes-farazsms

دکمهٔ Install را بزنید — تمام. دو نود Farazsms و Farazsms Trigger در لیست ظاهر می‌شوند. ✅

🚨 حتماً با @farazsms_official/ در ابتدا

پکیجی با نام مشابه n8n-nodes-farazsms (بدون @farazsms_official/) روی npm وجود دارد که متعلق به ما نیست، از شهریور ۱۴۰۴ به‌روزرسانی نشده، و به سرور ازکارافتادهٔ api.ippanel.com وصل می‌شود که روی همهٔ مسیرها خطای ۵۰۲ می‌دهد.

اگر خطای 502 Bad Gateway یا Faraz SMS API error می‌بینید، یا در نودتان فیلدی به نام Pattern Originator هست — پکیج اشتباه نصب شده. راهنمای مهاجرت: docs/TROUBLESHOOTING.md

🔑 اتصال در ۳ گام | Connect (3 steps)

1. در n8n یک Credential جدید از نوع Farazsms API بسازید.
2. API Key را از پنل فرازاس‌ام‌اس (بخش «وب‌سرویس / تنظیمات API») کپی کنید و اینجا بگذارید.
3. (اختیاری) Default Sender Line = شمارهٔ خط ارسال‌کننده را یک‌بار وارد کنید تا دیگر در هر نود تکرارش نکنید.

سپس دکمهٔ Test را بزنید؛ اگر همه‌چیز درست باشد، تیک سبز اتصال موفق را می‌بینید (پشت صحنه اعتبار حساب استعلام می‌شود). دیگر آزمون‌وخطا لازم نیست. 🎯

📨 نمونهٔ استفاده | Quick example

ارسال یک پیامک ساده:

1. نود Farazsms را اضافه کنید.
2. Resource = پیامک | Message · Operation = ارسال ساده | Send SMS
3. متن پیام و شماره‌های گیرنده (با کاما) را وارد کنید.
4. اجرا کنید.

خروجی نود تمیز و ساخت‌یافته است تا بتوانید در نودهای بعدی بر اساس آن تصمیم بگیرید:

{ "success": true, "status": "success", "data": 123456, "messages": null }

🩺 مشکلی پیش آمد؟ | Troubleshooting

اگر خطای 502 Bad Gateway یا Faraz SMS API error می‌بینید، به احتمال زیاد نودِ اشتباه نصب شده است. راهنمای کامل عیب‌یابی و پشتیبانی:

📖 docs/TROUBLESHOOTING.md

⚠️ نام دقیق پکیج ما @farazsms_official/n8n-nodes-farazsms است. پکیج مشابهی با نام n8n-nodes-farazsms (بدون @) روی npm وجود دارد که متعلق به ما نیست و به سرور از‌کار‌افتادهٔ api.ippanel.com وصل می‌شود.

🛠 مرجع فنی | Technical reference

• Base URL: https://api.iranpayamak.com
• Auth: هدر Api-Key (به‌صورت خودکار از Credential تزریق می‌شود)
• محدودیت نرخ: ۶۰ درخواست در دقیقه — نود خودش رعایتش می‌کند
• فرمت شماره: گیرنده باید دقیقاً 09xxxxxxxxx باشد (+98 و 0098 پذیرفته نمی‌شود)
• زمان‌بندی: مقدار Schedule Send به ساعت تهران تبدیل و ارسال می‌شود، چون سرور رشتهٔ بدون آفست را با Asia/Tehran می‌خواند. (استثنا: sms/postal/send سمت سرور با UTC می‌سنجد.)
• Endpoints: sms/simple · sms/pattern · sms/keywords · sms/bank · sms/postal/send · sms/postal/get-receiver-count · sms/postal/get-genders · sms/postal/get-available-lines · sms/calculate-cost · sms/voice/send · inbox · send_request · send_request/{id}/items · patterns · phone_book · phone_book_data · phone_book_data/bulk-upsert · number_bank · lines/accessible · account/balance
• تست: npm test — مجموعهٔ تست آفلاین، بدون شبکه و بدون ارسال پیامک واقعی
• وب‌سرویس: ایران‌پیامک | Iran Payamak
• مستندات کامل API: https://docs.iranpayamak.com
• وب‌سایت: فرازاس‌ام‌اس | Farazsms
• مخزن کد: https://gitlab.faraz.club/integrate/n8n

🗺 نقشهٔ راه | Roadmap

• v0.1: ارسال ساده/پترن/شخصی‌سازی، پیام صوتی، استعلام اعتبار، تست اتصال، DX دوزبانه.
• v0.2 (همین نسخه): نود Trigger دریافت پیامک · کمپین هدفمند (بانک شماره و کد پستی) · تخمین مخاطب و هزینه · گزارش تحویل تک‌گیرنده · دفترتلفن · فهرست کشویی پویا · مدیریت خودکار محدودیت نرخ · مجموعهٔ تست آفلاین.
• v0.3: ورک‌فلوهای آمادهٔ قابل‌کلون (OTP، سبد رهاشده، کمپین استانی، هشدار اعتبار) · ساخت و ویرایش پترن · کمپین موقعیت‌محور (LBS) · انتساب فروش با لینک ردیاب.

مجوز | License

MIT © Farazsms — powered by Iran Payamak