توضیحات افزونه
معماری کلی فلوها در n8n برای اتصال به SMS.ir
برای اینکه بتوانید ارسال پیامک با n8n را به‌صورت استاندارد و بدون پیچیدگی انجام دهید، کافی است از یک الگوی ثابت استفاده کنید. این الگو هم برای ارسال گروهی (Bulk) و هم برای ارسال با پترن (Verify) کاربرد دارد:
Form Trigger → Set → HTTP Request
- Form Trigger — نقطه‌ی ورود داده‌ها
در نسخه‌ی آموزشی، داده‌های تستی از طریق Form Trigger دریافت می‌شوند. مزیت این روش این است که در پروژه‌های واقعی می‌توانید همین نقطه‌ی ورود را با منابع دیگری مثل Webhook، دیتابیس یا حتی خروجی فلوهای قبلی در n8n جایگزین کنید؛ بدون اینکه منطق اصلی فلو تغییر کند.
- Set — آماده‌سازی داده برای API
در این مرحله داده‌ی خام ورودی به فرمت موردنیاز وب‌سرویس SMS.ir تبدیل می‌شود تا بدنه‌ی درخواست (Request Body) یک‌دست و استاندارد باشد:
- در حالت Bulk: لیست شماره موبایل‌ها ساخته و نرمال‌سازی می‌شود.
- در حالت Verify: آرایه‌ای از پارامترهای قالب (Template Parameters) ساخته می‌شود.
- HTTP Request — ارسال درخواست به SMS.ir
در گام پایانی، داده‌ی آماده‌شده با یک درخواست HTTP مستقیم به API SMS.ir ارسال می‌شود.
- برای ارسال گروهی: https://api.SMS.ir/v1/send/bulk
- برای ارسال با پترن : https://api.SMS.ir/v1/send/verify
خلاصه معماری
ورودی از Form گرفته می‌شود، در مرحله‌ی Set به فرمت درست تبدیل می‌گردد و در نهایت با HTTP Request به endpoint مناسب SMS.ir ارسال می‌شود. این الگوی ساده باعث می‌شود اتصال n8n به SMS.ir سریع، شفاف و مقیاس‌پذیر باشد.
بخش اول: ارسال گروهی (Bulk) در n8n با SMS.ir
یکی از رایج‌ترین سناریوها در اتوماسیون پیامکی، ارسال یک متن واحد به چند شماره موبایل است. در این بخش یک فلو ساده در n8n می‌سازیم که ورودی‌ها را از طریق فرم دریافت کرده، داده‌ها را در گام Set آماده‌سازی می‌کند و در نهایت با یک HTTP Request به وب‌سرویس SMS.ir ارسال می‌کند.
این همان چیزی است که به آن ارسال پیامک گروهی (Bulk SMS) گفته می‌شود. در پروژه‌های واقعی می‌توانید ورودی را به جای فرم از دیتابیس، Webhook یا هر منبع دیگری تأمین کنید و بقیه مراحل ثابت خواهد بود.
1) Form Trigger فیلدهای ورودی
برای تست شفاف و کامل، چهار فیلد زیر در فرم تعریف می‌شود:
- ApiKey (required): کلید وب‌سرویس SMS.ir برای احراز هویت.
- LineNumber (required): شماره خط ارسال‌کننده پیامک.
- MessageText (required): متن پیامک مشترک برای تمام مخاطبین.
- Mobiles (required): لیست شماره‌ها (امکان وارد کردن با کاما یا خط جدید).
2) Set نرمال‌سازی شماره‌ها (Normalize Inputs)
هدف این مرحله، تبدیل ورودی‌های کاربر به فرمت استانداردی است که API ارسال گروهی SMS.ir انتظار دارد (یعنی آرایه‌ای از شماره‌ها).
نمونه اکسپرشن مورد استفاده:
{{
(function(mobiles) {
if (Array.isArray(mobiles)) {
return mobiles.map(m => String(m).trim());
}
if (typeof mobiles === ‘number’) {
return [String(mobiles)];
}
if (typeof mobiles === ‘string’) {
return mobiles
.split(/[\n,]+/)
.map(m => m.trim())
.filter(Boolean);
}
return [];
})($json.Mobiles)
}}
این اکسپرشن ورودی‌ها را به شکل درست تبدیل می‌کند:
- “09120000001” → [“09120000001”]
- 9120000002 → [“9120000002”]
- “0912…,0913…” یا “0912…\n0913…” → [“0912…”,”0913…”]
3) HTTP Request ارسال به API Bulk
در این مرحله داده‌های آماده‌شده (شماره خط، متن پیام و لیست شماره‌ها) با یک درخواست HTTP به سرویس ارسال گروهی SMS.ir فرستاده می‌شود.
- Method: POST
- URL: https://api.SMS.ir/v1/send/bulk
- Send Headers: On
- Specify Headers: Using Fields Below
- Header Parameters:
- Name: X-API-KEY | Value: {{$json.ApiKey}}
- (در صورت نیاز: Content-Type به صورت پیش‌فرض JSON است و نیازی به تعریف جداگانه ندارد.)
- Send Body: On
- Body Content Type: JSON
- Specify Body: Using Fields Below
- Body Parameters (دقیقاً با همین حروف):
- Name: lineNumber | Value: {{$json.LineNumber}}
- Name: messageText | Value: {{$json.MessageText}}
- Name: mobiles | Value: {{$json.Mobiles}} (حتماً به صورت آرایه باشد؛ خروجی Set باید براکت [ ] داشته باشد)
📌 نکات مهم:
- کلیدها را دقیقاً با حروف مشخص‌شده بنویسید (lineNumber, messageText, mobiles).
- مطمئن شوید خروجی نود Set واقعاً یک آرایه است (نه رشته).
- مقدار X-API-KEY حتماً باید در Header ارسال شود.
4) نتیجه موفق و پاسخ API
در صورت موفقیت، پاسخ وب‌سرویس چیزی شبیه به این خواهد بود:
{
“status”: 1,
“message”: “موفق”,
“data”: {
“packId”: “…”,
“messageIds”: [86522023, 86522024],
“cost”: 2.0
}
}
- status = 1 یعنی درخواست پذیرفته شده است.
- packId شناسه مجموعه ارسال (برای گزارش‌گیری و پیگیری).
- messageIds[] شناسه هر پیامک ارسال‌شده.
این ساختار ساده به شما کمک می‌کند خیلی سریع، ارسال پیامک گروهی با n8n را از طریق SMS.ir پیاده‌سازی کنید.
بخش دوم: ارسال پیامک با پترن (Verify) در n8n و SMS.ir
گاهی اوقات متن پیام از قبل در سامانه SMS.ir به صورت یک قالب (Template) تعریف می‌شود. در این حالت کافی است فقط TemplateId و مقادیر متغیرها (مثلاً Code یا OTP) را ارسال کنید.
این روش برای ارسال پیامک‌های مهم مثل کد تأیید (OTP)، اعلان‌های حساس یا پیامک‌های خدماتی استفاده می‌شود، چون از خطوط خدماتی و با اولویت بالا ارسال می‌گردد.
1) Form Trigger — فیلدهای ورودی
برای تست سریع و شفاف، در فرم چهار فیلد زیر کافی است:
- ApiKey (required): کلید وب‌سرویس برای احراز هویت در SMS.ir.
- Mobile (required): شماره موبایل گیرنده پیامک.
- TemplateId (required): شناسه قالبی که در پنل SMS.ir ساخته‌اید.
- Code (required): مقدار متغیر (مثلاً کد تأیید) که در قالب تعریف شده است.
2) Set — ساخت آرایه‌ی parameters
در این سناریو باید یک آرایه به نام parameters ایجاد شود تا مقدار متغیرهای قالب در آن قرار بگیرد
- . در نود Set یک فیلد جدید بسازید به نام parameters
- Type: روی Array بگذارید (خیلی مهم)
- Value (Expression): این اکسپرشن را دقیقاً قرار دهید تا از فیلد «Code» فرم، آرایهٔ پارامتر بسازد:
{{
(function(c){
const val = String(c ?? ”).trim();
return val ? [{ name: ‘Code’, value: val }] : [];
})($json.Code)
}}
📌 نکات مهم:
- اگر در قالب به جای #Code# از #OTP# استفاده کرده‌اید، کافی است مقدار name را به OTP تغییر دهید و یا هر نام متغیر دیگری که در قالب شما وجود دارد.
- برای چند متغیر، می‌توانید چند فیلد در فرم بگذارید (مثل Code و Name) و در خروجی Set چند آبجکت {name, value} اضافه کنید.
.
- 3) HTTP Request —فراخوانی API Verify
در این مرحله داده‌ها (شماره گیرنده، شناسه قالب و پارامترها) به سرویس ارسال سریع SMS.ir ارسال می‌شوند.
Method: POST
URL: https://api.SMS.ir/v1/send/verify
Send Headers: On
- Specify Headers: Using Fields Below
- Header Parameters:
Name: X-API-KEY | Value: {{$json.ApiKey}}
Send Body: On
- Body Content Type: JSON
- Specify Body: Using Fields Below
- Body Parameters (دقیقاً با همین حروف):
- Name: Mobile | Value: {{$json.Mobile}}
- Name: TemplateId | Value: {{$json.TemplateId}}
- Name: Parameters | Value: {{$json.Parameters}} (حتماً آرایه باشد
4) نتیجه موفق و پاسخ API (Verify)
بعد از اجرای موفق فلو، پاسخ وب‌سرویس Verify SMS.ir به این شکل خواهد بود:
{
“data”: {
“messageId”: 262290516,
“cost”: 1
},
“status”: 1,
“message”: “موفق”
}
status = 1 یعنی درخواست با موفقیت پذیرفته شده است.
message مقدار متنی پاسخ است (در صورت موفق معمولاً «موفق»).
data.messageId شناسه‌ی یکتای پیامک ارسال‌شده است (برای پیگیری و گزارش).
data.cost نشان‌دهنده تعداد پیامک مصرف‌شده یا هزینه‌ی ارسال است.
با همین سه گام، ارسال Verify آماده است: داده‌ها را در فرم می‌گیرید، فقط parameters را بر اساس نام‌های قالب می‌سازید و درخواست JSON را به endpoint مخصوص SMS.ir می‌فرستید.
دانلود و ایمپورت ورک‌فلوها در n8n
برای اینکه سریع‌تر شروع کنید، می‌توانید هر دو ورک‌فلو آماده (Bulk و Verify) را از گیت‌هاب دانلود کرده و به‌طور مستقیم در n8n ایمپورت کنید:
🔗 مشاهده و دانلود ورک‌فلوها در GitHub
روش ایمپورت از فایل (Import from File)
- در صفحه‌ی Overview روی Create Workflow کلیک کنید.
- در بوم خالی، منوی سه‌نقطه (کنار دکمه Save) را باز کرده و Import from File… را بزنید.
- یکی از فایل‌های آماده را انتخاب کنید:
- smsir-bulk-send.json (برای ارسال گروهی)
- smsir-verify-send.json (برای ارسال با پترن)
- روی Save → Execute بزنید؛ فرم ورودی باز می‌شود. ApiKey و سایر فیلدها را وارد کنید و ارسال را تست نمایید.
روش ایمپورت از URL (Import from URL)
اگر ترجیح می‌دهید مستقیماً از URL استفاده کنید:
- در گیت‌هاب روی فایل موردنظر کلیک کنید.
- روی Raw بزنید و آدرس را کپی کنید.
- در n8n گزینه Import from URL… را انتخاب کرده و همان آدرس را Paste کنید.
با این دو روش، در کمتر از چند دقیقه می‌توانید ورک‌فلوهای آماده‌ی ارسال پیامک با n8n و SMS.ir را اجرا کنید و بلافاصله آن‌ها را مطابق نیاز خود سفارشی‌سازی نمایید.
جمع‌بندی
در این آموزش دیدیم که چطور می‌توان با یک الگوی ساده و تکرارشونده در n8n (یعنی Form → Set → HTTP Request) دو نیاز مهم پیامکی را پیاده‌سازی کرد:
- ارسال گروهی پیامک (Bulk SMS) برای اعلان‌ها، یادآوری‌ها و کمپین‌ها
- ارسال پیامک با پترن (Verify SMS) برای کد تأیید (OTP) و پیام‌های حساس از طریق خطوط خدماتی
با اتصال n8n به وب‌سرویس SMS.ir، فرآیند ارسال پیامک هم سریع‌تر می‌شود، هم شفاف‌تر و هم بدون نیاز به کدنویسی پیچیده.
حالا شما می‌توانید همین الگو را به جای فرم آزمایشی، با منابع داده واقعی مثل دیتابیس، وب‌هوک یا حتی خروجی فلوهای قبلی جایگزین کنید و در مقیاس دلخواه کسب‌وکار خود به کار بگیرید.
به این ترتیب، یکپارچه‌سازی ارسال پیامک در n8n با SMS.ir نه‌تنها ساده است، بلکه قابلیت سفارشی‌سازی و مقیاس‌پذیری بالایی هم دارد.
