راهنمای استفاده از نود باسلام برای n8n

معرفی

نود Basalam در n8n این امکان را می‌دهد که پیام‌های متنی و تصاویر را از طریق بات باسلام ارسال کنید و همچنین با کمک وب‌هوک‌ها (Trigger) به پیام‌ها و رویدادهای جدید واکنش نشان دهید.
برای استفاده از این نود لازم است یک کرندنشیال اختصاصی با نام basalamApi پیکربندی کنید. در ادامه به آموزش پیکربندی و استفاده، می‌پردازیم.

• نام پکیج: n8n-nodes-basalam

قابلیت‌ها

• ارسال پیام متنی: chat → Bot Send Message
• ارسال تصویر (باینری): chat → Bot Send Photo
• پشتیبانی از Reply Markup شامل:Force Reply ،Reply Keyboard و Reply Keyboard Remove
• پشتیبانی از فیلدهای اختیاری پیام مانند: reply_to_message_id, disable_notification و …
• نود Trigger برای دریافت آپدیت‌ها (تنظیم یا حذف وب‌هوک از طریق Bot API)

پیش‌نیازها

• نصب n8n نسخه 1.x یا بالاتر
• داشتن Bot Token سرویس گفت‌وگوی باسلام: برای دریافت Bot Token باید در گفت‌وگوی باسلام به @botfather  مراجعه کرده و بات خود را ایجاد کنید.
• دسترسی برای نصب نودهای سفارشی (Community Nodes) در محیط n8n

نصب

نصب از طریق رابط کاربری n8n (Community Nodes)

1. در منوی n8n به بخش Settings → Community Nodes بروید.
2. روی Install کلیک کنید و نام پکیج را وارد کنید: n8n-nodes-basalam
3. پس از نصب، در صورت نیاز n8n را ری‌استارت کنید.

پیکربندی کرندنشیال (Credentials)

بعد از نصب نود:

1. به بخش Credentials در n8n بروید و یک کرندنشیال جدید از نوع basalamApi بسازید.
2. فیلد botToken (توکن بات شما که از @botfather در مراحل قبل دریافت کردید) را تکمیل کنید.
3. کرندنشیال را ذخیره کنید.

شروع سریع

1. یک Workflow جدید ایجاد کنید.
2. نود Basalam را اضافه کنید.
3. در بخش Resource مقدار chat را انتخاب کرده و سپس در Operation یکی از گزینه‌ها را انتخاب کنید:
   • Bot Send Message: ارسال پیام متنی
   • Bot Send Photo: ارسال عکس باینری
4. فیلدها را تنظیم کنید:
   • Chat ID: شناسه چت مقصد
   • برای Bot Send Message: فیلد Text
   • برای Bot Send Photo: فیلد Input Binary Field و در صورت نیاز Caption
   • در صورت نیاز از بخش‌های Reply Markup و Additional Fields استفاده کنید
5. کرندنشیال basalamApi را انتخاب کنید.
6. Workflow را اجرا کنید.

نکات و عیب‌یابی

• در ارسال عکس، اگر fileName مشخص نشده باشد ولی در متادیتای باینری وجود داشته باشد، به‌صورت خودکار استفاده می‌شود. در غیر این صورت باید در بخش Additional Fields → File Name مقدار بدهید.
• در صورت عدم ارسال پیام، botUrl و botToken را بررسی کنید و مطمئن شوید Endpointهای سرویس گفت‌وگو در دسترس هستند.
• برای دریافت پیام‌های ورودی، از نود Basalam Trigger استفاده کنید تا وب‌هوک در سرویس به‌طور خودکار تنظیم شود.