در این راهنما یاد می‌گیرید چگونه از بخش Integrations در Rocket.Chat یک Webhook ایجاد کنید تا بتوانید پیام‌ها را از سرویس‌های دیگر به Rocket.Chat ارسال کنید یا هنگام وقوع رویدادهای مختلف، اطلاعات را از Rocket.Chat به سرویس‌های دیگر ارسال کنید.

Integration چیست؟

Integration قابلیتی در Rocket.Chat است که امکان ارتباط این سرویس با نرم‌افزارها و سرویس‌های دیگر را فراهم می‌کند. این ارتباط معمولاً از طریق Webhook انجام می‌شود.

دو نوع Webhook در Rocket.Chat وجود دارد:

• Incoming Webhook برای ارسال پیام از یک سرویس خارجی به Rocket.Chat
• Outgoing Webhook برای ارسال اطلاعات از Rocket.Chat به یک سرویس خارجی

ورود به بخش Integrations

پس از ورود به Rocket.Chat، از علامت چرخ‌دنده روی Administration کلیک کنید. سپس از بخش Workspace گزینه Integrations را انتخاب کنید.

در این صفحه فهرست تمامی Integrationهای ایجادشده نمایش داده می‌شود و می‌توانید Integration جدید ایجاد یا موارد قبلی را مدیریت کنید.

ایجاد یک Integration جدید

در صفحه Integrations روی دکمه New Integration کلیک کنید. در این مرحله باید نوع Integration را انتخاب کنید. بسته به نیاز خود می‌توانید یکی از گزینه‌های زیر را انتخاب کنید:

• Incoming WebHook
• Outgoing WebHook

ایجاد Incoming Webhook

مرحله اول: ورود به بخش Incoming Webhook

از منوی Administration وارد بخش Integrations شوید. سپس تب Incoming را انتخاب کنید تا فرم ساخت یک Incoming Webhook نمایش داده شود. در این صفحه تنظیمات مربوط به دریافت پیام از سرویس‌های خارجی را انجام می‌دهید.

مرحله دوم: تنظیمات اصلی Webhook را تکمیل کنید

ابتدا اطلاعات اصلی Integration را وارد کنید تا Rocket.Chat بداند پیام‌های دریافتی را چگونه مدیریت کند.

فعال کردن Integration

گزینه Enabled را فعال کنید. در غیر این صورت، Webhook ایجاد می‌شود اما درخواست‌های ارسالی را پردازش نخواهد کرد.

انتخاب نام

در قسمت Name یک نام برای Integration وارد کنید. این نام فقط در بخش مدیریت Rocket.Chat نمایش داده می‌شود و بهتر است نشان دهد این Webhook برای چه کاری استفاده می‌شود؛ برای مثال GitHub Notifications یا n8n Alerts.

تعیین مقصد پیام‌ها

در قسمت Post to Channel مشخص کنید پیام‌های دریافتی در کجا نمایش داده شوند.

اگر مقصد یک کانال است، نام آن را همراه با # وارد کنید؛ مانند:

#general

اگر می‌خواهید پیام برای یک کاربر ارسال شود، نام کاربری را همراه با @ بنویسید.

@john

انتخاب فرستنده پیام

در قسمت Post as کاربری را انتخاب کنید که پیام‌ها با نام او در Rocket.Chat منتشر شوند. این کاربر باید از قبل در ورک‌اسپیس وجود داشته باشد.

مرحله سوم: ظاهر پیام را در صورت نیاز شخصی‌سازی کنید

در صورت نیاز می‌توانید ظاهر پیام‌هایی که از طریق Webhook ارسال می‌شوند را تغییر دهید.

در قسمت Alias یک نام مستعار وارد کنید تا به جای نام کاربر ارسال‌کننده نمایش داده شود.

اگر می‌خواهید پیام با تصویر متفاوتی نمایش داده شود، آدرس تصویر را در قسمت Avatar URL وارد کنید. همچنین می‌توانید به‌جای تصویر، در قسمت Emoji یک ایموجی مانند :rocket: یا :ghost: قرار دهید تا به‌عنوان آواتار پیام نمایش داده شود.

اگر گزینه Allow to overwrite destination channel in the body parameters را فعال کنید، سرویس ارسال‌کننده می‌تواند هنگام ارسال درخواست، کانال مقصد را نیز در Payload مشخص کند. در این حالت، پیام لزوماً به کانالی که در Post to Channel انتخاب کرده‌اید ارسال نمی‌شود.

اگر همیشه می‌خواهید پیام‌ها فقط در یک کانال مشخص منتشر شوند، این گزینه را غیرفعال نگه دارید.

مرحله چهارم: در صورت نیاز از Script استفاده کنید

Rocket.Chat امکان اجرای کد JavaScript را قبل از انتشار پیام فراهم می‌کند. این قابلیت برای زمانی مناسب است که بخواهید اطلاعات دریافتی را تغییر دهید، بخشی از آن را حذف کنید یا قالب پیام را قبل از ارسال سفارشی کنید.

برای استفاده از این قابلیت، گزینه Script Enabled را فعال کنید.

در قسمت Script Sandbox می‌توانید محیط اجرای اسکریپت را انتخاب کنید. برای Integrationهای جدید، استفاده از Secure Sandbox پیشنهاد می‌شود.

در نهایت، کد JavaScript موردنظر را در قسمت Script وارد کنید.

اگر فقط قصد دریافت و نمایش پیام را دارید، نیازی به فعال کردن این بخش نیست.

مرحله پنجم: اطلاعات اتصال را دریافت کنید

پس از تکمیل تنظیمات، روی Save کلیک کنید.

بعد از ذخیره، بخشی با عنوان Instructions نمایش داده می‌شود که اطلاعات لازم برای اتصال سرویس‌های دیگر به Rocket.Chat را در اختیار شما قرار می‌دهد.

Webhook URL

این آدرس، نقطه اتصال Webhook است. هر برنامه یا سرویسی که درخواست HTTP POST را به این آدرس ارسال کند، می‌تواند پیام خود را در Rocket.Chat منتشر کند.

Token

این مقدار شناسه اختصاصی Webhook است که توسط Rocket.Chat ایجاد می‌شود و برای شناسایی این Integration استفاده می‌شود. از آنجایی که این مقدار بخشی از اطلاعات اتصال است، آن را در اختیار افراد غیرمجاز قرار ندهید.

Example payload

Rocket.Chat در این بخش یک نمونه از ساختار داده‌ای که باید به Webhook ارسال شود نمایش می‌دهد.

{
  "text": "Workflow completed successfully",
  "attachments": [
    {
      "title": "n8n Workflow",
      "title_link": "https://n8n.example.com",
      "text": "Daily Backup completed successfully.",
      "color": "#2ECC71"
    }
  ]
}

در این نمونه، فیلد text متن اصلی پیام را مشخص می‌کند. بخش attachments نیز برای افزودن اطلاعات تکمیلی مانند عنوان، لینک، تصویر و رنگ استفاده می‌شود و استفاده از آن اختیاری است.

اگر فقط قصد ارسال یک پیام ساده را دارید، کافیست Payload زیر را به Webhook URL ارسال کنید.

{
  "text": "سلام، این پیام از طریق Incoming Webhook ارسال شده است."
}

ایجاد Outgoing Webhook

مرحله اول: ورود به بخش Outgoing Webhooks

از منوی Administration وارد بخش Workspace شوید. سپس از منوی Integrations، روی New Integration کلیک کرده و گزینه Outgoing Webhook را انتخاب کنید.

مرحله دوم: تکمیل تنظیمات اصلی

در این بخش مشخص می‌کنید این Integration چه زمانی اجرا شود و درخواست را به چه آدرسی ارسال کند.

• Enabled: این گزینه را فعال کنید تا Integration پس از ذخیره قابل استفاده باشد.
• Name: یک نام برای Integration وارد کنید تا بعداً بتوانید آن را به‌راحتی شناسایی کنید. برای مثال: n8n Command Handler
• Event Trigger: نوع رویدادی را انتخاب کنید که باعث اجرای Webhook شود.
• Channel: مشخص کنید پیام‌ها از کدام کانال یا کاربر بررسی شوند. برای کانال از # و برای کاربر از @ استفاده کنید. برای مثال:
  • #general
  • @john
  • all_public_channels برای همه کانال‌های عمومی
  • all_private_groups برای همه گروه‌های خصوصی
  • all_direct_messages برای همه پیام‌های مستقیم
• Trigger Words: کلمه یا عبارت آغازکننده دستور را وارد کنید. هر زمان پیامی با یکی از این کلمات شروع شود، Outgoing Webhook اجرا خواهد شد. اگر چند کلمه دارید، آن‌ها را با کاما (,) از هم جدا کنید. برای مثال:

  deploy,status,help
  

• URLs: آدرس مقصدی را وارد کنید که Rocket.Chat درخواست را به آن ارسال می‌کند. این آدرس معمولاً مربوط به یک API، سرویس n8n یا برنامه‌ای است که قرار است پیام را پردازش کند.

مرحله سوم: تنظیم نحوه نمایش پاسخ

در این بخش مشخص می‌کنید اگر سرویس مقصد پاسخی به Rocket.Chat برگرداند، آن پیام با چه ظاهری نمایش داده شود.

• Impersonate User: در صورت نیاز می‌توانید پیام پاسخ را به نام کاربر ارسال کنید.
• Post as: کاربری را انتخاب کنید که پاسخ Integration با نام او در کانال نمایش داده شود. این کاربر باید از قبل در Workspace وجود داشته باشد.
• Alias: یک نام نمایشی برای پیام‌ها وارد کنید. این نام قبل از نام کاربری نمایش داده می‌شود.
• Avatar URL: در صورت تمایل آدرس تصویر آواتار را وارد کنید.
• Emoji: به جای تصویر می‌توانید از یک ایموجی به‌عنوان آواتار استفاده کنید. برای مثال:

  :robot_face:
  

• Token: یک مقدار امنیتی است که برای اعتبارسنجی درخواست‌ها استفاده می‌شود. این مقدار به‌صورت خودکار ایجاد می‌شود و معمولاً نیازی به تغییر آن نیست.

مرحله چهارم: تنظیم Script

اگر می‌خواهید قبل از ارسال درخواست یا نمایش پاسخ، کد JavaScript اجرا شود، این بخش را پیکربندی کنید.

• Script Enabled: اجرای Script را فعال یا غیرفعال می‌کند.
• Script Sandbox: برای Scriptهای جدید، گزینه Secure Sandbox را انتخاب کنید. گزینه Compatible Sandbox فقط برای Scriptهای قدیمی کاربرد دارد.
• Script: کد JavaScript موردنظر را در این بخش وارد کنید.

اگر قصد استفاده از Script را ندارید، این بخش را بدون تغییر رها کنید.

مرحله پنجم: قالب پاسخ سرویس

اگر سرویس مقصد پس از دریافت درخواست، پاسخی با قالب JSON به Rocket.Chat برگرداند، همان پاسخ به‌صورت یک پیام در کانال نمایش داده می‌شود.

نمونه پاسخ:

{
  "text": "Example message",
  "attachments": [
    {
      "title": "Rocket.Chat",
      "title_link": "https://rocket.chat",
      "text": "Rocket.Chat, the best open source chat",
      "image_url": "https://your-domain/images/integration-attachment-example.png",
      "color": "#764FA5"
    }
  ]
}

در این نمونه، فیلد text متن اصلی پیام را مشخص می‌کند. بخش attachments نیز برای نمایش اطلاعات تکمیلی مانند عنوان، لینک، تصویر و رنگ استفاده می‌شود. استفاده از این بخش اختیاری است.

اگر پاسخ فقط شامل یک متن ساده باشد، کافیست سرویس مقصد JSON زیر را برگرداند:

{
  "text": "دستور با موفقیت اجرا شد."
}

مرحله ششم: تنظیمات پیشرفته

در بخش Advanced Settings می‌توانید رفتار Outgoing Webhook را در شرایط مختلف کنترل کنید.

• Retry Failed URL Calls: اگر ارتباط با URL مقصد برقرار نشد، Rocket.Chat دوباره درخواست را ارسال می‌کند.
• Retry Count: تعداد دفعات تلاش مجدد را مشخص می‌کند.
• Retry Delay: نحوه افزایش فاصله زمانی بین تلاش‌های مجدد را تعیین می‌کند.
• Word Placement Anywhere: اگر این گزینه فعال باشد، Trigger Word می‌تواند در هر قسمت از پیام قرار داشته باشد. در غیر این صورت، پیام باید با Trigger Word شروع شود.
• Run On Edits: اگر فعال باشد، با ویرایش پیام نیز Outgoing Webhook اجرا می‌شود. در صورت غیرفعال بودن، فقط هنگام ارسال پیام جدید اجرا خواهد شد.

پس از تکمیل تنظیمات، روی Save کلیک کنید تا Outgoing Webhook ایجاد شود.

نکات مهم

Webhook URL و Token را محرمانه نگه دارید.
هر شخصی که به اطلاعات اتصال یک Incoming Webhook دسترسی داشته باشد، می‌تواند به ورک‌اسپیس شما پیام ارسال کند. در صورت افشای این اطلاعات، Webhook را حذف کرده و یک Webhook جدید ایجاد کنید.

در تنظیمات کانال، نام کانال را همراه با # و نام کاربر را همراه با @ وارد کنید.
در غیر این صورت Rocket.Chat خطای Invalid channel نمایش می‌دهد.

در Outgoing Webhook، آدرس مقصد باید امکان دریافت درخواست HTTP را داشته باشد.
اگر URL مقصد در دسترس نباشد یا پاسخ مناسبی برنگرداند، Integration به‌درستی عمل نخواهد کرد.

از Script فقط در صورت نیاز استفاده کنید.
اگر فقط قصد ارسال یا دریافت پیام را دارید، نیازی به فعال کردن Script نیست و بهتر است آن را غیرفعال نگه دارید.

سوالات متداول

تفاوت Incoming Webhook و Outgoing Webhook چیست؟

Incoming Webhook برای ارسال پیام از یک سرویس خارجی به Rocket.Chat استفاده می‌شود. در مقابل، Outgoing Webhook هنگام وقوع یک رویداد یا ارسال پیام در Rocket.Chat، اطلاعات را به یک سرویس خارجی ارسال می‌کند.

چرا Webhook اجرا نمی‌شود؟

ابتدا بررسی کنید گزینه Enabled فعال باشد. سپس از صحیح بودن Webhook URL یا URL مقصد، تنظیمات کانال و دسترسی سرویس مقصد اطمینان حاصل کنید.

چرا خطای Invalid channel نمایش داده می‌شود؟

این خطا معمولاً زمانی رخ می‌دهد که نام کانال یا کاربر را بدون # یا @ وارد کرده باشید یا کانال موردنظر در Workspace وجود نداشته باشد.

آیا می‌توان یک Webhook را برای چند کانال استفاده کرد؟

بله. در Incoming Webhook می‌توانید گزینه Allow to overwrite destination channel in the body parameters را فعال کنید تا سرویس ارسال‌کننده، کانال مقصد را هنگام ارسال درخواست مشخص کند. در Outgoing Webhook نیز می‌توانید با تنظیم Channel، یک کانال، یک کاربر یا چندین کانال را برای اجرای Integration انتخاب کنید.

آیا برای استفاده از Webhook به برنامه‌نویسی نیاز است؟

خیر. برای ایجاد و مدیریت Webhook در Rocket.Chat نیازی به برنامه‌نویسی نیست. تنها در صورتی که بخواهید پیام‌ها را قبل از ارسال یا دریافت پردازش یا سفارشی‌سازی کنید، می‌توانید از بخش Script و کد JavaScript استفاده کنید.