ارسال پیام متنی
sendMessage با chat_id و text؛ پشتیبانی از parse_mode برای لینک، بولد و منشن. پایهایترین و پایدارترین endpoint روی همه پیامرسانها.
گردشکار n8n و Make را بدون نوشتن بکاند به پیامرسان وصل کنید
تیم محصول و عملیات میخواهد یک ردیف جدید در Google Sheets، یک فرم یا یک هشدار مانیتورینگ را به پیام ایتا، بله یا تلگرام تبدیل کند؛ ولی هر بار باید منتظر مهندس بماند. یونیوم همان قالب آشنای Telegram Bot API را روی HTTP میگذارد، تا یک HTTP Request در n8n یا Make با یک کلید محدود، ارسال و دریافت پیام را پوشش دهد.
۱ HTTP Request
۱ وبهوک مشترک
۵ گام گردشکار
۱ کلید محدود
تریگروبهوک یونیوم در n8n/Make
درخواست HTTPPOST به api.uniom.ir با Authorization
پاسخپاسخ روی حساب مجاز و لاگشده
هر تغییر کوچک، منتظر یک مهندس است
پیامرسانهای ایرانی SDK رسمی برای n8n ندارند و قالب API هر کدام متفاوت است. نتیجه این میشود: اپراتور میخواهد متن یک یادآوری را عوض کند یا یک پلتفرم را اضافه کند، اما باید برای تیم فنی تیکت بزند و منتظر بماند. وقتی هم کد سفارشی نوشته میشود، خطا و تکرار رویداد بهسادگی نادیده گرفته میشود؛ یک وبهوک که دو بار تحویل داده شد، میتواند دو سفارش یا دو پیام کاربر بسازد.
یونیوم جای کد را پر نمیکند؛ آن را یکسان میکند. یک endpoint، یک هدر Authorization و یک قالب JSON برای همه پیامرسانها، تا بخش بزرگی از اتوماسیون بدون نوشتن بکاند قابل اجرا باشد و زمانی هم که حجم بالا رفت، مهاجرت به کد واقعی فقط تغییر کلاینت باشد، نه بازطراحی.
- بدون SDK اختصاصی برای هر پلتفرم؛ فقط یک HTTP Request و یک JSON body.
- قالب سازگار با Telegram Bot API، پس sampleهای آماده n8n برای تلگرام با تغییر base_url کار میکنند.
- کلید API با scope محدود، مخصوص گردشکار غیرفنی، قابل ابطال فوری.
- وبهوک برای رویدادهای ورودی؛ long polling هم برای زمانی که وبهوک مقدور نیست.
یک گردشکار n8n چطور ساخته میشود
مسیر کامل، از یک ردیف جدید در شیت تا پیام تحویلشده روی پیامرسان، با ذکر نکات خطا و تکرار.
۱. تریگر
یک نود وبهوک یا تریگر Google Sheets در n8n/Make قرار دهید. برای رویدادهای ورودی پیامرسان، وبهوک یونیوم را به همان نود وصل کنید تا پیام جدید وارد گردشکار شود.
۲. آمادهسازی body
در نود Set یا Function، فیلدها را بسازید: chat_id، text و در صورت نیاز parse_mode. شناسه پیام ورودی را در یک کلید نگه دارید برای گام تکرارناپذیری.
۳. درخواست HTTP
POST به https://api.uniom.ir/bot/sendMessage بزنید. هدر Authorization: Bearer <api-key> و Content-Type: application/json. بدنه همان قالب آشنای Bot API است.
۴. Error branch
اگر یونیوم ۴xx یا ۵xx برگرداند (مثلاً INVALID_AUTH یا transport failed)، پیام را در یک شیت خطا بنویسید، نه اینکه گردشکار خاموش بماند. این کار بازبینی دستی را ممکن میکند.
۵. ثبت نتیجه
message_id برگشتی از پاسخ موفق را در شیت یا دیتابیس خودتان ذخیره کنید؛ برای پیگیری تحویل، تفکیک کلیدها و رفع تداخل بعدی لازم است.
اولین وبهوک باید با یک کلید توسعه و یک حساب آزمایشی تست شود. صبر نکنید تا حجم بالا برود تا مسیر خطا و تکرار را طراحی کنید.
چه کارهایی بدون کد قابل اجرا است
هر کار بالا با یک HTTP Request و بدون نوشتن بکاند، مادامی که محدودیت پلتفرم مقصد رعایت شود.
دریافت پیام ورودی
وبهوک یونیوم را به نود Webhook در n8n وصل کنید تا پیام کاربر وارد گردشکار شود؛ برای پاسخ خودکار یا ثبت تیکت پشتیبانی.
مدیا و فایل
sendPhoto، sendDocument و sendVoice برای فاکتور، تصویر محصول و یادآوری صوتی. پشتیبانی از مدیا روی همه credentialها یکسان نیست؛ جدول پلتفرم را ببینید.
دکمه و منو
inline_keyboard و reply_markup برای منوی انتخاب سرویس یا تأیید سفارش؛ پاسخ callback_query به همان شکل قالب تلگرام بازمیگردد.
کلید با scope
برای هر گردشکار یک کلید جدا با دسترسی فقطارسال بسازید؛ ابطال کلید یک اتوماسیون، بقیه را تحت تأثیر قرار نمیدهد.
لاگ قابل تفکیک
هر درخواست با api_key_id و credential_id ثبت میشود؛ در داشبورد میتوانید ببینید کدام گردشکار، کدام پیام را فرستاده و چه خطایی گرفته است.
چیزی که در ابزار بدون کد نباید رها کنید
ابزار بدون کد بهسادگی خطا را پنهان میکند؛ یک نادیدهگرفتن کوچک میشود اسپم یا سفارش تکراری. این موارد را بهصورت آگاهانه در گردشکار طراحی کنید، نه بعد از حادثه.
- تکرار وبهوک را idempotent طراحی کنید: یک پیام که دو بار تحویل میشود نباید دو بار در شیت یا CRM درج شود؛ شناسه پیام را بهعنوان کلید یکتا استفاده کنید.
- محدودیت نرخ را نادیده نگیرید: ارسال بدون فاصله یا در حجم بالا میتواند به 429 یا شکست سشن منجر شود؛ بین درخواستها تأخیر یا صف قرار دهید.
- خطای ۴xx/۵xx را خاموش رها نکنید: INVALID_AUTH یا transport failed یعنی پیام نرفته؛ بدون Error branch، اپراتور متوجه نمیشود.
- کلید مشترک برای همه گردشکارها نسازید: یک کلید صرفاً خواندن یا صرفاً ارسال نگه دارید؛ دامنه انفجار یک خطا را کوچک نگه میدارد.
- تأیید رضایت را فراموش نکنید: ارسال انبوه بدون رضایت کاربر، خارج از قواعد پلتفرم است و اعتبار حساب را به ریسک میاندازد.
گردشکارهای متداول روی n8n و Make
ردیف جدید در شیت ← پیام
تریگر Google Sheets به ازای هر ردیف جدید، یک پیام وضعیت سفارش یا خوشآمد به کاربر میفرستد؛ message_id در همان شیت ثبت میشود.
فرم ← کلاینت غایب
ارسال فرم وبسایت (مثلاً وبهوک از Nabfield یا فرم داخلی) به یونیوم؛ کلاینت پیام را روی بله یا ایتا میگیرد و پاسخ در شیت ذخیره میشود.
هشدار مانیتورینگ ← تیم
وبهوک Grafana/UptimeRobot را مستقیم به یونیوم وصل نکنید؛ از طریق درخواست HTTP یونیوم، هشدار را به کانال یا گروه تیم روی تلگرام/سروشپلاس بفرستید.
پیام ورودی ← تیکت
پیام دریافتی کاربر از وبهوک یونیوم در n8n گرفته میشود، در شیت پشتیبانی یا CRM درج میشود و تأیید رسید به کاربر برمیگردد.
برای Make.com الگوی کار یکسان است؛ تفاوت فقط در نام نودهاست (ماژول HTTP بهجای درخواست HTTP، ماژول وبهوک بهجای نود وبهوک). قالب JSON بدنه فرقی نمیکند.
چه زمان گردشکار بدون کد دیگر کافی نیست
صف و کنترل نرخ
وقتی حجم به هزاران پیام در ساعت میرسد، retry/backoff و صف واقعی لازم است؛ n8n با یک صف PostgreSQL یا Redis بهتر از حلقهی نود درمیآید، ولی بالاتر از آن باید به کد مهاجرت کنید.
منطق پیچیده
اگر پاسخ به تاریخ، وضعیت کاربر یا محتوای پیام وابسته است و چندین شرط تودرتو لازم دارد، کد خواناتر و قابلتستتر از یک Flow عظیم نود است.
تأیید انسانی
وقتی برخی پیامها باید پیش از ارسال توسط اپراتور تأیید شوند، یک صف پیشنویس در دیتابیس خودتان روشنتر از обход کار در ابزار بدون کد است.
پایش جدی
در حجم عملیاتی، داشبورد نرخ موفقیت، تأخیر و خطا بر اساس لاگ یونیوم + متریکهای خودتان لازم است؛ آن زمان تاریخ انقضای کد رسیده.
خبر خوب: چون قالب درخواست همان Bot API است، مهاجرت از n8n به کد فقط ساختن یک HTTP client با همان base_url و همان Authorization است، نه بازطراحی API.
کدام پلتفرم برای گردشکار شما مناسب است
انتخاب بر اساس ویژگی فنی و مخاطب، نه فقط نام آشنا. این قابلیتها روی همه credentialها معنی یکسان ندارد؛ جدول هر پلتفرم را قبل از راهاندازی بخوانید.
- بات رسمی تلگرام (BotFather): باثباتترین گزینه برای اتوماسیون، webhook پایدار و inline keyboard کامل؛ ولی بهخاطر فیلترینگ، رسیدگیانی به کاربر وابسته است.
- بله: قالب Bot API رسمی (بازو) دارد، inline keyboard و حتی درگاه پرداخت درونبات؛ انتخاب طبیعی برای اتوماسیون فروش و دولتمحور.
- ایتا: دسترسی از لایه account API یونیوم (بات رسمی ندارد)؛ عالی برای کانالها و یادآوری، ولی محدودیت مدیا و نرخ را جدی بگیرید.
- سروشپلاس: «بدون فیلتر» یعنی رسید مطمئن؛ لایه bot رسمی هنوز آزمایشی است، پس account API یونیوم مسیر پایدار است.
- روبیکا: بیشترین کاربر فعال روزانه میان پیامرسانهای ایرانی؛ برای اطلاعرسانی انبوه به کاربران داخلی قوی، ولی بلوغ رسمی ربات هنوز در حال شکلگیری است.
چکلیست قبل از فعالسازی گردشکار
- یک حساب آزمایشی به یونیوم وصل کنید و کلید توسعه با scope فقطارسال بسازید.
- در Playground، یک sendMessage واقعی بفرستید و پاسخ ok و message_id را ببینید.
- وبهوک را روی یک محیط آزمایش n8n/Make وصل کنید و یک پیام ورودی را داخل گردشکار بگیرید.
- شناسه پیام ورودی را بهعنوان کلید تکرارناپذیری در شیت یا دیتابیس ذخیره کنید تا تکرار وبهوک دو بار درج نکند.
- یک Error branch بسازید: ۴xx/۵xx را در یک شیت خطا بنویسید و گردشکار را متوقف نکنید.
- بین درخواستهای ارسال، تأخیر یا صف قرار دهید تا محدودیت نرخ پلتفرم مقصد نقض نشود.
- پس از تأیید مسیر، کلید عملیاتی جدا با scope محدود بسازید و گردشکار را روی آن سوئیچ کنید.
- در داشبورد، لاگ ارسال و خطا را چند روز پایش کنید و سپس حجم را بالا ببرید.
پلتفرمهای اتوماسیون که با یک HTTP Request وصل میشوند
یونیوم روی لبهی همین HTTP ساده نشسته است؛ بنابراین هر ابزاری که نود HTTP دارد، میتواند ارسال و دریافت پیام را از یونیوم بگیرد.
n8n
نود Webhook یونیوم را trigger کنید و پاسخ را با HTTP Request برگردانید؛ قالب پیام همان Bot API است.
Make (Integromat)
سناریوی Make با ماژول HTTP: یک webhook ورودی برای پیامهای جدید و یک webhook خروجی برای پاسخ.
Zapier
Zap از وبهوک یونیوم شروع میشود و به هر اپ متصل متصل میشود؛ ارسال پاسخ از مرحلهی Webhook دوم.
Google Sheets
سادهترین حالت: ردیف جدید در شیت یک پیام میفرستد و پاسخ در ستون وضعیت به شیت برمیگردد.
کلید idempotency را با message_id بسازید تا تکرار وبهوک، پیام یا ردیف تکراری نسازد.
اولین گردشکار را با یک کلید بسازید
یک کلید توسعه با scope محدود بسازید، در Playground درخواست را تست کنید و بعد آن را به نود HTTP Request در n8n یا Make وصل کنید.