نود Whatsapp Business Cloud در N8N
نود WhatsApp Business Cloud در n8n
نود WhatsApp Business Cloud در n8n به شما کمک میکند ارسال و دریافت پیامهای واتساپ را بهصورت حرفهای و خودکار انجام دهید؛ از ارسال پیامهای متنی و قالبدار (Template) تا مدیریت پیامهای ورودی و اتصال آنها به سیستمهای CRM، تیکتینگ، فروش و پشتیبانی. اگر میخواهید با کمترین کدنویسی یک «ربات پاسخگو» یا «سیستم اعلان واتساپی» بسازید، این نود یکی از کلیدیترین ابزارهای شماست.
معرفی نود در n8n
کارکرد نود
این نود برای کار با WhatsApp Business Cloud API (سرویس رسمی متا) طراحی شده و معمولاً برای این کارها استفاده میشود:
- ارسال پیام به کاربران (متن، قالب Template، رسانه و …)
- دریافت پیامهای ورودی از طریق Webhook (وقتی کاربر پیام میدهد)
- مدیریت رویدادها مثل تحویل/خواندهشدن پیام (Status Updates)
دستهبندی نود
- Integration: اتصال مستقیم به سرویس WhatsApp Business Cloud
- Trigger (بهصورت رایج با Webhook): دریافت پیامها و رویدادها
- Action: ارسال پیام و انجام عملیات API
اهمیت در ورکفلوها
واتساپ یکی از کانالهای اصلی ارتباط با مشتری است. با این نود میتوانید:
- اعلانهای حیاتی (کد ورود، وضعیت سفارش، پیگیری پرداخت) را سریع و قابل اتکا ارسال کنید
- پشتیبانی نیمهخودکار بسازید (اتصال به FAQ، تیکت، اپراتور)
- کمپینهای مبتنی بر Template را با کنترل و گزارشگیری اجرا کنید
موارد استفاده
سناریوهای واقعی
- اعلان وضعیت سفارش: بعد از تغییر وضعیت سفارش در فروشگاه، به مشتری پیام واتساپی ارسال شود.
- ارسال کد یکبارمصرف (OTP): پس از درخواست ورود، کد را از طریق Template ارسال کنید.
- پشتیبانی خودکار: پیام ورودی کاربر دریافت شود، دستهبندی شود و پاسخ مناسب ارسال گردد.
- یادآوری نوبت/جلسه: یک روز قبل از زمان رزرو، پیام یادآوری ارسال شود.
- جمعآوری لید: کاربر پیام میدهد، اطلاعاتش ثبت میشود و یک پیام خوشآمد ارسال میگردد.
سناریوهای متداول در n8n
- Webhook (Trigger) → پردازش پیام → پاسخ واتساپی
- Google Sheets/CRM Trigger → WhatsApp Send Message
- Stripe/PayPal Trigger → WhatsApp Template (پرداخت موفق/ناموفق)
ترکیب با نودهای دیگر برای ورکفلوهای عملی
- Webhook برای دریافت رویدادهای WhatsApp Cloud
- IF برای تشخیص نوع پیام (متن/دستور/کلمه کلیدی)
- Set برای ساخت بدنه پیام و پارامترها
- HTTP Request برای استفاده از مسیرهای خاص API در صورت نبود عملیات آماده
- Google Sheets / Airtable / Notion برای ذخیره لید، لاگ پیامها و پیگیری
- OpenAI برای ساخت پاسخ هوشمند (با کنترل و محدودیت)
پارامترها و تنظیمات
در n8n بسته به نسخه و نوع پیادهسازی نود، نام دقیق فیلدها ممکن است کمی متفاوت باشد، اما مفاهیم و فیلدهای اصلی WhatsApp Cloud تقریباً ثابت هستند. در این بخش، فیلدهای کلیدی و کاربردی را بهصورت استاندارد توضیح میدهیم.
اتصال و احراز هویت (Credentials)
- Access Token (String): توکن دسترسی Cloud API. برای ارسال پیام و دسترسی به API لازم است. مثال: EAAG… (توکن طولانی متا)
- Phone Number ID (String/Number): شناسه شماره واتساپی که از طریق Meta دریافت میکنید. مثال: 123456789012345
- Business Account ID (String/Number): شناسه حساب بیزینس (گاهی برای برخی عملیات لازم میشود). مثال: 987654321098765
- API Version (String): نسخه Graph API. مثال: v19.0 یا v20.0
نکته عملی: اگر به هر دلیل نود آماده در n8n برخی عملیات را پوشش نداد، با همان Access Token و Phone Number ID میتوانید از نود HTTP Request استفاده کنید و دقیقاً مطابق مستندات متا فراخوانی بزنید.
پارامترهای ارسال پیام (Action: Send Message)
- To (String): شماره گیرنده با فرمت بینالمللی (بدون + و بدون فاصله). مثال: 989121234567
- Messaging Product (String): معمولاً مقدار ثابت whatsapp. مثال: whatsapp
- Type (String): نوع پیام. مقادیر رایج: text، template، image، document، audio، video، interactive. مثال: text
- Preview URL (Boolean – برای پیام متنی): اگر متن لینک دارد، تعیین میکند پیشنمایش لینک نمایش داده شود یا نه. مثال: false
- Text Body (String – برای type=text): متن پیام. مثال: سلام! سفارش شما ثبت شد.
پارامترهای پیام Template (برای پیامهای خارج از 24 ساعت یا پیامهای رسمی)
- Template Name (String): نام تمپلیت تاییدشده در واتساپ بیزینس. مثال: order_update
- Language Code (String): کد زبان تمپلیت. مثال: fa یا en_US
- Components (Array): پارامترهای جایگذاری (متن/هدر/دکمه). مثال: پارامترهای {{1}}، {{2}} داخل تمپلیت
نکته مهم: پیامهای غیر Template معمولاً فقط داخل پنجره 24 ساعته (Customer Care Window) مجاز هستند. اگر کاربر بیش از 24 ساعت قبل پیام داده باشد، برای شروع مکالمه باید Template ارسال شود.
پارامترهای رسانه (Image/Document/Video)
- Media Link (String): لینک عمومی فایل (HTTPS) که واتساپ بتواند دانلود کند. مثال: https://example.com/invoice.pdf
- Caption (String): توضیح زیر رسانه (در برخی انواع). مثال: فاکتور سفارش شما
- Filename (String – برای Document): نام فایل نمایشی. مثال: invoice-1024.pdf
نکته عملی: اگر فایل شما خصوصی است، ابتدا آن را روی یک فضای قابل دانلود موقت (مثل S3 با لینک امضا شده) قرار دهید، سپس لینک را به واتساپ بدهید.
پارامترهای پیامهای تعاملی (Interactive)
- Interactive Type (String): button یا list و … بسته به API. مثال: button
- Header / Body / Footer (String): اجزای متن پیام تعاملی. مثال: لطفاً یکی را انتخاب کنید
- Buttons / List Items (Array): گزینهها با id و title. مثال: id=track_order
نکته مهم: برای اتوماسیونهای منظم، گزینهها را با idهای ثابت طراحی کنید تا در پردازش پیامهای ورودی راحتتر Route انجام شود.
تنظیمات دریافت پیام (Trigger/Webhook)
- Webhook Verify Token (String): توکنی که برای تایید Webhook در متا استفاده میشود. مثال: n8n_verify_123
- Webhook URL (String): آدرس Webhook که از n8n میگیرید و در Meta تنظیم میکنید.
- Subscribed Fields (Array): رویدادهایی که میخواهید دریافت کنید (messages، message_status و …).
نکته عملی: در n8n اگر از Webhook Node استفاده میکنید، حتماً حالت Production URL را در Meta ثبت کنید (نه Test URL)، و Workflow را Active نگه دارید.
ورودیها و خروجیها
ورودی (Input) نود
در حالت Action (ارسال پیام)، ورودی معمولاً از نودهای قبلی میآید و شما فیلدهایی مثل شماره گیرنده و متن را با Expression از ورودی میخوانید. نمونه ورودی متداول:
{ "to": "989121234567", "type": "text", "text": { "preview_url": false, "body": "سلام! سفارش شما با موفقیت ثبت شد." }}
خروجی (Output) نود
پس از ارسال موفق، API معمولاً شناسه پیام را برمیگرداند. نمونه خروجی:
{ "messaging_product": "whatsapp", "contacts": [ { "input": "989121234567", "wa_id": "989121234567" } ], "messages": [ { "id": "wamid.HBgMOTg5MTIxMjM0NTY3FQIAERgS..." } ]}
نمونه ساختار پیام ورودی (Webhook) از سمت واتساپ
وقتی کاربر پیام میدهد، Webhook یک payload نسبتاً مفصل ارسال میکند. یک نمونه سادهشده:
{ "object": "whatsapp_business_account", "entry": [ { "id": "WHATSAPP_BUSINESS_ACCOUNT_ID", "changes": [ { "field": "messages", "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "15551234567", "phone_number_id": "123456789012345" }, "contacts": [ { "profile": { "name": "Ali" }, "wa_id": "989121234567" } ], "messages": [ { "from": "989121234567", "id": "wamid....", "timestamp": "1700000000", "type": "text", "text": { "body": "سلام" } } ] } } ] } ]}
نکته عملی: در n8n معمولاً مسیر دسترسی به متن پیام چیزی شبیه این میشود: entry[0].changes[0].value.messages[0].text.body
نکات پیشرفته و ترفندها
1) مدیریت پنجره 24 ساعته با ذخیره آخرین تعامل
برای جلوگیری از خطا در ارسال پیامهای غیر Template، زمان آخرین پیام کاربر را ذخیره کنید (مثلاً در Airtable/DB). سپس با یک IF بررسی کنید اگر بیش از 24 ساعت گذشته بود، بهجای text یک template ارسال شود.
2) Route کردن پیامها با Interactive IDs
اگر از دکمهها/لیستها استفاده کنید، کاربر بهجای متن آزاد، یک id مشخص میفرستد. این کار باعث میشود پردازش قابل اعتمادتر شود:
- IF: اگر id برابر track_order بود → درخواست وضعیت سفارش از API فروشگاه
- IF: اگر id برابر talk_to_agent بود → ساخت تیکت و اطلاع به اپراتور
3) جلوگیری از ارسال تکراری با Idempotency ساده
شناسه پیام ورودی (messages[0].id) را در یک دیتابیس/شیت ذخیره کنید. اگر همان id دوباره رسید (گاهی به دلیل retry)، پاسخ تکراری ارسال نکنید.
4) لاگگیری کامل برای عیبیابی
در کنار ارسال/دریافت، یک کپی از payloadها را در یک جدول (Google Sheets/DB) ذخیره کنید:
- wa_id
- type
- message_id
- timestamp
- status (sent/delivered/read/failed)
- error (اگر وجود داشت)
5) استفاده از HTTP Request برای قابلیتهای خاص
اگر عملیات خاصی در نود آماده نبود، فراخوانی استاندارد ارسال پیام با HTTP Request معمولاً این شکل است:
POST https://graph.facebook.com/v20.0/{PHONE_NUMBER_ID}/messagesAuthorization: Bearer {ACCESS_TOKEN}Content-Type: application/json
بدنه (Body) هم مطابق ساختارهای نمونهای است که در بخش ورودی دیدید.
محدودیتها و خطاها
محدودیتها
- قوانین پیامرسانی واتساپ: خارج از پنجره 24 ساعته، فقط Template مجاز است (برای پیامهای شروع مکالمه).
- نیاز به Template تاییدشده: قالبها باید در Meta تایید شوند و نام/پارامترها دقیق باشد.
- فرمت شماره: شمارهها باید با کد کشور و بدون + ارسال شوند.
- محدودیت رسانه: لینک فایل باید قابل دسترس باشد؛ در غیر این صورت ارسال شکست میخورد.
- کیفیت و محدودیت ارسال: محدودیتهای سطح شماره (Messaging Limits) و Quality Rating میتواند روی تعداد ارسال اثر بگذارد.
خطاهای رایج و راهحلها
- Invalid OAuth access token / Expired token: توکن منقضی یا اشتباه است. توکن را بازتولید و در Credentials بهروزرسانی کنید.
- Unsupported post request / Wrong Phone Number ID: Phone Number ID اشتباه است یا به حساب شما تعلق ندارد. مقدار را از Meta دقیق کپی کنید.
- Recipient phone number not in allowed list (در حالت تست): در محیط تست، فقط شمارههای اضافهشده به لیست تست پیام میگیرند. شماره را در پنل Meta اضافه کنید یا حساب را به حالت تولید ببرید.
- Template name does not exist / Parameter mismatch: نام Template یا تعداد پارامترها با قالب تاییدشده یکی نیست. دقیقاً مطابق Template تنظیم کنید.
- Message outside allowed window: پنجره 24 ساعته تمام شده است. بهجای پیام متنی، Template ارسال کنید.
- Media download failed: لینک فایل عمومی نیست یا TLS/ریدایرکت مشکل دارد. لینک مستقیم HTTPS و قابل دانلود ارائه دهید.
ایده ها
- سیستم پیگیری سفارش واتساپی: کاربر با زدن دکمه «پیگیری»، وضعیت سفارش از API خوانده و ارسال شود.
- ربات نوبتدهی: لیست زمانهای خالی از Google Calendar خوانده شود و کاربر با دکمه انتخاب کند.
- اتصال فرم سایت به واتساپ: بعد از ثبت فرم (Typeform/Elementor/Webhook)، پیام خوشآمد و مراحل بعدی ارسال شود.
- گردش کار تیکتینگ: پیامهای ورودی به Zendesk/Freshdesk تبدیل به تیکت شوند و شماره تیکت برای کاربر ارسال گردد.
- هشدارهای مالی: با رخدادهای Stripe، پیامهای Template برای پرداخت موفق/ناموفق و رسید ارسال شود.