نانوپ
مستندات n8n
74+ نود

مستندات n8n

74+ نود مستند شده · ۰ بازدید

👥

مایکروسافت تیمز

Microsoft Teams

اتوماسیون Microsoft Teams: ارسال پیام، Adaptive Cards، مدیریت تیم، جلسات آنلاین و اعلان سازمانی

ارتباطات
متوسط
۰ بازدید
n8n 1.0+

نمای کلی

نود Microsoft Teams یکی از مهم‌ترین نودهای n8n برای ارتباطات سازمانی و اتوماسیون فرآیندهای کسب‌وکار در محیط Microsoft 365 است.

Microsoft Teams چیست؟

Microsoft Teams پلتفرم ارتباطات و همکاری سازمانی مایکروسافت است که پیام‌رسانی، تماس صوتی/تصویری، جلسات آنلاین، اشتراک فایل و یکپارچه‌سازی با ابزارهای Microsoft 365 (Word, Excel, SharePoint, OneDrive) را در یک محیط متمرکز ارائه می‌دهد. Microsoft Graph API امکان اتوماسیون کامل Teams را فراهم می‌کند.

قابلیت‌های کلیدی:

  • ارسال پیام متنی و HTML به کانال‌ها و چت‌ها
  • ارسال Adaptive Cards (پیام‌های تعاملی پیشرفته)
  • ایجاد و مدیریت تیم‌ها و کانال‌ها
  • مدیریت اعضای تیم (اضافه/حذف)
  • زمان‌بندی و ایجاد جلسات آنلاین (Online Meetings)
  • آپلود و اشتراک فایل در کانال‌ها
  • پاسخ در Thread (Reply to Message)
  • @mention کاربران و تیم‌ها
  • دریافت لیست تیم‌ها، کانال‌ها و اعضا
  • یکپارچه‌سازی با SharePoint و OneDrive

Microsoft Teams Trigger:

  • دریافت پیام جدید در کانال
  • رویدادهای عضویت در تیم
  • تغییرات در کانال‌ها
  • رویدادهای جلسات آنلاین
  • Webhook‌های ورودی (Incoming Webhooks)

کاربردها در سازمان‌ها:

  • اعلان‌های سیستم‌های داخلی (ERP, CRM, HR)
  • هشدار مانیتورینگ سرور و سرویس‌ها
  • مدیریت فرآیندهای تایید (Approval Workflows)
  • اعلان تیکت‌های پشتیبانی و Incident
  • گزارش‌های روزانه و هفتگی مدیریتی
  • زمان‌بندی خودکار جلسات
  • یکپارچه‌سازی با Azure DevOps و GitHub
  • اتوماسیون Onboarding کارمندان جدید

احراز هویت

احراز هویت Microsoft Teams

روش ۱: OAuth2 با Azure AD (توصیه شده)

#### مراحل ساخت Azure AD App Registration:

  1. 1به [Azure Portal](https://portal.azure.com) بروید
  2. 2به بخش Azure Active Directory > App registrations بروید
  3. 3روی New registration کلیک کنید
  4. 4تنظیمات:
code
Name: n8n Teams Integration
   Supported account types: Accounts in this organizational directory only
   Redirect URI: https://your-n8n-url/rest/oauth2-credential/callback
  1. 1Register را بزنید

#### دریافت Client ID و Secret:

  1. 1از صفحه Overview، Application (client) ID را کپی کنید
  2. 2Directory (tenant) ID را نیز یادداشت کنید
  3. 3به Certificates & secrets > New client secret بروید:
code
Description: n8n Integration
   Expires: 24 months (توصیه شده)
  1. 1Value (نه Secret ID) را فوراً کپی کنید

#### تنظیم API Permissions (Microsoft Graph): به API permissions > Add a permission > Microsoft Graph بروید:

Delegated Permissions (برای OAuth2):

code
Channel.ReadBasic.All         → خواندن اطلاعات کانال‌ها
ChannelMessage.Send           → ارسال پیام در کانال
ChannelMessage.Read.All       → خواندن پیام‌های کانال
Chat.ReadWrite                → خواندن و نوشتن چت‌ها
ChatMessage.Send              → ارسال پیام در چت
Group.ReadWrite.All           → مدیریت تیم‌ها (Groups)
Team.ReadBasic.All            → خواندن اطلاعات تیم‌ها
TeamMember.ReadWrite.All      → مدیریت اعضای تیم
OnlineMeetings.ReadWrite      → مدیریت جلسات آنلاین
Files.ReadWrite.All           → آپلود و مدیریت فایل‌ها
User.Read                     → خواندن پروفایل کاربر جاری
User.Read.All                 → خواندن پروفایل تمام کاربران

Application Permissions (برای سرویس بدون کاربر):

code
ChannelMessage.Read.All       → خواندن تمام پیام‌ها
Team.ReadBasic.All            → خواندن تیم‌ها
TeamMember.Read.All           → خواندن اعضا
OnlineMeetings.Read.All       → خواندن جلسات
  1. 1Grant admin consent را بزنید (نیاز به دسترسی Global Admin)

#### تنظیم در n8n:

  1. 1Credentials > Microsoft Teams OAuth2 API
  2. 2فیلدها:
code
Client ID: [Application (client) ID از Azure]
   Client Secret: [Secret Value از Azure]
   Tenant ID: [Directory (tenant) ID] (یا "common" برای Multi-tenant)
  1. 1Connect بزنید و با حساب Microsoft وارد شوید
  2. 2دسترسی‌ها را تایید کنید

روش ۲: Incoming Webhook (ساده‌ترین روش)

برای فقط ارسال پیام به یک کانال خاص:

  1. 1در Teams: کانال مورد نظر > Connectors (یا Manage channel > Connectors)
  2. 2Incoming Webhook را پیدا و Configure کنید
  3. 3نام و آیکون Webhook را تنظیم کنید
  4. 4Create بزنید و URL را کپی کنید:
code
https://outlook.office.com/webhook/xxx/IncomingWebhook/yyy/zzz
  1. 1این URL را در HTTP Request Node در n8n استفاده کنید

#### مزایای Webhook:

  • نیازی به Azure AD Registration ندارد
  • تنظیم سریع و بدون دردسر
  • مناسب برای اعلان‌های یک‌طرفه
  • پشتیبانی از Adaptive Cards

#### محدودیت‌های Webhook:

  • فقط ارسال پیام (نه خواندن یا مدیریت)
  • محدود به یک کانال خاص
  • بدون دسترسی به API مدیریتی

روش ۳: Bot Framework (پیشرفته)

برای ساخت ربات تعاملی کامل:

  1. 1در [Bot Framework Portal](https://dev.botframework.com) ثبت‌نام کنید
  2. 2Bot را ایجاد و به Teams Channel متصل کنید
  3. 3Messaging Endpoint را به n8n Webhook وصل کنید

نکات امنیتی:

  • Client Secret را در محل امن نگهداری کنید
  • از حداقل دسترسی‌های مورد نیاز استفاده کنید (Principle of Least Privilege)
  • Secret را قبل از انقضا تمدید کنید
  • برای محیط Production از Certificate (نه Secret) استفاده کنید
  • دسترسی Conditional Access را برای App تنظیم کنید
  • Activity Logs را در Azure AD مانیتور کنید

عملیات‌های موجود

1

send_message

ارسال پیام متنی یا HTML به کانال تیم. پشتیبانی از فرمت‌بندی HTML، @mention کاربران، لینک‌ها و تصاویر inline. پیام در کانال برای تمام اعضای تیم قابل مشاهده است.

2

send_chat_message

ارسال پیام مستقیم (DM) به یک کاربر یا گروه چت. برای ارتباط خصوصی یا گروهی بدون نیاز به ایجاد تیم مناسب است. پشتیبانی از فرمت HTML و Adaptive Cards.

3

send_card

ارسال Adaptive Card (کارت تعاملی) به کانال یا چت. Adaptive Cards امکان نمایش فرم‌ها، دکمه‌ها، تصاویر، جداول و ورودی‌های تعاملی را فراهم می‌کنند. از Adaptive Cards Designer برای طراحی بصری استفاده کنید.

4

reply_to_message

ارسال پاسخ در Thread یک پیام موجود در کانال. پاسخ‌ها زیر پیام اصلی نمایش داده می‌شوند و مکالمات را سازمان‌یافته نگه می‌دارند. برای ادامه بحث در موضوع خاص مناسب است.

5

create_channel

ایجاد کانال جدید در یک تیم. کانال‌ها فضاهای بحث و همکاری در تیم هستند. می‌توانید کانال Standard (قابل مشاهده برای همه اعضا) یا Private (فقط اعضای دعوت‌شده) ایجاد کنید.

6

list_channels

دریافت لیست تمام کانال‌های یک تیم شامل نام، توضیحات، نوع عضویت و تاریخ ایجاد. برای یافتن Channel ID مناسب برای ارسال پیام یا مدیریت کانال‌ها استفاده می‌شود.

7

get_channel

دریافت اطلاعات کامل یک کانال شامل نام، توضیحات، نوع عضویت، وضعیت و آدرس ایمیل کانال. برای بررسی تنظیمات کانال یا دریافت جزئیات قبل از ارسال پیام مفید است.

8

update_channel

ویرایش نام یا توضیحات یک کانال موجود. کانال General (پیش‌فرض) قابل حذف نیست اما نام و توضیحاتش قابل تغییر است. برای به‌روزرسانی Topic یا وضعیت کانال مناسب است.

9

list_members

دریافت لیست تمام اعضای یک تیم شامل نام، ایمیل، نقش (owner/member/guest) و اطلاعات کاربری. برای مدیریت اعضا، تولید گزارش و بررسی دسترسی‌ها استفاده می‌شود.

10

add_member

اضافه کردن کاربر جدید به تیم به عنوان عضو (Member) یا مالک (Owner). کاربر باید در Azure AD سازمان وجود داشته باشد. کاربران مهمان (Guest) از خارج سازمان نیز قابل دعوت هستند.

11

create_team

ایجاد تیم جدید در Microsoft Teams. تیم یک فضای همکاری شامل کانال‌ها، فایل‌ها و برنامه‌ها است. به صورت خودکار یک Microsoft 365 Group نیز ایجاد می‌شود. برای پروژه‌ها، بخش‌ها یا تیم‌های کاری جدید مناسب است.

12

list_teams

دریافت لیست تمام تیم‌هایی که کاربر عضو آنهاست. شامل نام، توضیحات، تعداد اعضا و وضعیت آرشیو. برای یافتن Team ID مناسب و مدیریت تیم‌ها استفاده می‌شود.

13

upload_file

آپلود فایل به پوشه SharePoint مرتبط با کانال تیم. فایل‌ها در تب Files کانال قابل مشاهده هستند. پشتیبانی از تمام فرمت‌ها: PDF، Excel، Word، تصاویر و غیره. حداکثر حجم فایل 250MB.

14

create_meeting

ایجاد جلسه آنلاین (Online Meeting) در Microsoft Teams با لینک شرکت در جلسه. امکان تنظیم زمان شروع و پایان، موضوع، شرکت‌کنندگان و تنظیمات Lobby. لینک جلسه قابل اشتراک‌گذاری با افراد خارج از سازمان نیز هست.

کاربردهای متداول

کاربردهای رایج

۱. اعلان‌های سیستم داخلی (ERP/CRM)

ارسال اعلان رویدادهای مهم سیستم به کانال تیم:

code
Webhook (رویداد CRM: سفارش جدید)
  → Set (فرمت‌بندی داده‌ها)
  → Microsoft Teams (send_card)
    TeamId: SALES_TEAM_ID
    ChannelId: ORDERS_CHANNEL_ID
    Card:
      {
        "type": "AdaptiveCard",
        "body": [
          {"type": "TextBlock", "text": "سفارش جدید ثبت شد", "weight": "bolder", "size": "large"},
          {"type": "FactSet", "facts": [
            {"title": "شماره سفارش", "value": "${orderId}"},
            {"title": "مشتری", "value": "${customerName}"},
            {"title": "مبلغ", "value": "${amount} تومان"},
            {"title": "وضعیت", "value": "در انتظار تایید"}
          ]},
          {"type": "TextBlock", "text": "محصولات: ${items}", "wrap": true}
        ],
        "actions": [
          {"type": "Action.OpenUrl", "title": "مشاهده سفارش", "url": "${orderUrl}"},
          {"type": "Action.OpenUrl", "title": "تایید سفارش", "url": "${approveUrl}"}
        ]
      }

۲. هشدار مانیتورینگ و Incident

ارسال هشدار فوری هنگام Down شدن سرویس:

code
Schedule (هر 2 دقیقه)
  → HTTP Request (Health Check سرویس‌ها)
  → IF (status != 200)
    → Microsoft Teams (send_message)
      TeamId: DEVOPS_TEAM_ID
      ChannelId: ALERTS_CHANNEL_ID
      ContentType: html
      Importance: urgent
      Content:
        <h3>هشدار: سرویس از دسترس خارج شد!</h3>
        <table>
          <tr><td><b>سرویس:</b></td><td>${serviceName}</td></tr>
          <tr><td><b>URL:</b></td><td>${url}</td></tr>
          <tr><td><b>Status:</b></td><td>${statusCode}</td></tr>
          <tr><td><b>زمان:</b></td><td>${timestamp}</td></tr>
        </table>
        <p><at id="0">${oncallUser}</at> لطفا بررسی کنید.</p>

۳. فرآیند تایید درخواست (Approval Workflow)

مدیریت درخواست‌های مرخصی و هزینه:

code
Webhook (درخواست مرخصی از سیستم HR)
  → Microsoft Teams (send_card)
    ChatId: MANAGER_CHAT_ID
    Card:
      {
        "type": "AdaptiveCard",
        "body": [
          {"type": "TextBlock", "text": "درخواست مرخصی جدید", "weight": "bolder", "size": "large", "color": "accent"},
          {"type": "ColumnSet", "columns": [
            {"type": "Column", "items": [
              {"type": "TextBlock", "text": "کارمند:", "weight": "bolder"},
              {"type": "TextBlock", "text": "نوع مرخصی:"},
              {"type": "TextBlock", "text": "از تاریخ:"},
              {"type": "TextBlock", "text": "تا تاریخ:"},
              {"type": "TextBlock", "text": "توضیحات:"}
            ]},
            {"type": "Column", "items": [
              {"type": "TextBlock", "text": "${employeeName}"},
              {"type": "TextBlock", "text": "${leaveType}"},
              {"type": "TextBlock", "text": "${startDate}"},
              {"type": "TextBlock", "text": "${endDate}"},
              {"type": "TextBlock", "text": "${reason}", "wrap": true}
            ]}
          ]}
        ],
        "actions": [
          {"type": "Action.Submit", "title": "تایید", "style": "positive", "data": {"action": "approve", "requestId": "${id}"}},
          {"type": "Action.Submit", "title": "رد", "style": "destructive", "data": {"action": "reject", "requestId": "${id}"}},
          {"type": "Action.OpenUrl", "title": "مشاهده جزئیات", "url": "${detailUrl}"}
        ]
      }

۴. زمان‌بندی خودکار جلسات

ایجاد جلسه هفتگی Sprint Review:

code
Schedule (هر دوشنبه ساعت 8:00)
  → Microsoft Teams (create_meeting)
    Subject: "Sprint Review - هفته ${weekNumber}"
    StartDateTime: ${nextThursday}T14:00:00+03:30
    EndDateTime: ${nextThursday}T15:30:00+03:30
    Participants: [
      {emailAddress: {address: "pm@company.com"}, type: "required"},
      {emailAddress: {address: "dev-lead@company.com"}, type: "required"},
      {emailAddress: {address: "qa-lead@company.com"}, type: "optional"}
    ]
    LobbyBypassScope: organization
  → Microsoft Teams (send_message)
    ChannelId: SPRINT_CHANNEL_ID
    Content:
      "جلسه Sprint Review این هفته:
       زمان: پنجشنبه ساعت 14:00
       لینک: ${joinUrl}
       لطفا Demo خود را آماده کنید."

۵. Onboarding کارمند جدید

اتوماسیون فرآیند ورود کارمند جدید:

code
Webhook (کارمند جدید از سیستم HR)
  → Microsoft Teams (add_member)
    TeamId: COMPANY_TEAM_ID
    UserId: ${newEmployeeEmail}
    Role: member
  → Microsoft Teams (add_member)
    TeamId: ${departmentTeamId}
    UserId: ${newEmployeeEmail}
  → Microsoft Teams (send_message)
    ChannelId: GENERAL_CHANNEL_ID
    ContentType: html
    Content:
      "<h3>به تیم ما خوش آمدید!</h3>
       <p><at id='0'>${newEmployeeName}</at> به عنوان ${jobTitle}
       به تیم ${department} پیوست.</p>
       <p>لطفا خوش‌آمد بگویید! 👋</p>"
  → Microsoft Teams (send_chat_message)
    ChatId: DM_WITH_NEW_EMPLOYEE
    Content:
      "سلام ${firstName}!
       به شرکت خوش آمدید.
       راهنمای شروع کار: ${onboardingUrl}
       در صورت هرگونه سوال با منتور خود تماس بگیرید."

۶. گزارش روزانه خودکار

ارسال آمار روزانه به تیم مدیریت:

code
Schedule (هر روز ساعت 18:00)
  → Database (آمار فروش، کاربران، تیکت‌ها)
  → Code (پردازش و فرمت‌بندی)
  → Microsoft Teams (send_card)
    TeamId: MANAGEMENT_TEAM_ID
    ChannelId: REPORTS_CHANNEL_ID
    Card:
      {
        "type": "AdaptiveCard",
        "body": [
          {"type": "TextBlock", "text": "گزارش روزانه - ${today}", "weight": "bolder", "size": "large"},
          {"type": "ColumnSet", "columns": [
            {"type": "Column", "items": [
              {"type": "TextBlock", "text": "${totalOrders}", "size": "extraLarge", "color": "good", "horizontalAlignment": "center"},
              {"type": "TextBlock", "text": "سفارش", "horizontalAlignment": "center"}
            ]},
            {"type": "Column", "items": [
              {"type": "TextBlock", "text": "${revenue}", "size": "extraLarge", "color": "accent", "horizontalAlignment": "center"},
              {"type": "TextBlock", "text": "درآمد (تومان)", "horizontalAlignment": "center"}
            ]},
            {"type": "Column", "items": [
              {"type": "TextBlock", "text": "${newUsers}", "size": "extraLarge", "color": "warning", "horizontalAlignment": "center"},
              {"type": "TextBlock", "text": "کاربر جدید", "horizontalAlignment": "center"}
            ]}
          ]},
          {"type": "FactSet", "facts": [
            {"title": "تیکت‌های باز", "value": "${openTickets}"},
            {"title": "میانگین زمان پاسخ", "value": "${avgResponseTime}"},
            {"title": "رضایت مشتری", "value": "${satisfaction}%"}
          ]}
        ],
        "actions": [
          {"type": "Action.OpenUrl", "title": "مشاهده داشبورد کامل", "url": "${dashboardUrl}"}
        ]
      }

۷. یکپارچه‌سازی Azure DevOps / GitHub

اعلان رویدادهای CI/CD:

code
GitHub Trigger (push to main / PR merged)
  → Microsoft Teams (send_card)
    ChannelId: DEVOPS_CHANNEL_ID
    Card:
      {
        "type": "AdaptiveCard",
        "body": [
          {"type": "TextBlock", "text": "Deploy جدید به Production", "weight": "bolder", "color": "good"},
          {"type": "FactSet", "facts": [
            {"title": "Branch", "value": "${branch}"},
            {"title": "Commit", "value": "${commitMessage}"},
            {"title": "Author", "value": "${author}"},
            {"title": "Build", "value": "#${buildNumber}"},
            {"title": "Status", "value": "موفق ✅"}
          ]}
        ],
        "actions": [
          {"type": "Action.OpenUrl", "title": "مشاهده تغییرات", "url": "${compareUrl}"},
          {"type": "Action.OpenUrl", "title": "Build Logs", "url": "${buildUrl}"}
        ]
      }

۸. مدیریت تیکت پشتیبانی

اعلان تیکت جدید و مدیریت در Teams:

code
Webhook (تیکت جدید از سایت)
  → Microsoft Teams (send_message)
    ChannelId: SUPPORT_CHANNEL_ID
    ContentType: html
    Importance: high
    Content:
      "<h3>تیکت جدید #${ticketId}</h3>
       <b>موضوع:</b> ${subject}<br>
       <b>مشتری:</b> ${customerName}<br>
       <b>اولویت:</b> ${priority}<br>
       <b>دسته:</b> ${category}"
  → Microsoft Teams (reply_to_message)
    MessageId: ${parentMessageId}
    Content: "جزئیات: ${description}"

۹. چرخش On-Call و هشدار شیفت

مدیریت خودکار شیفت‌های آنکال:

code
Schedule (هر دوشنبه ساعت 9:00)
  → Database (دریافت نوبت آنکال جاری)
  → Microsoft Teams (update_channel)
    TeamId: OPS_TEAM_ID
    ChannelId: ONCALL_CHANNEL_ID
    Description: "آنکال این هفته: ${oncallName} | تلفن: ${oncallPhone}"
  → Microsoft Teams (send_card)
    ChannelId: ONCALL_CHANNEL_ID
    Card:
      {
        "type": "AdaptiveCard",
        "body": [
          {"type": "TextBlock", "text": "تغییر شیفت آنکال", "weight": "bolder"},
          {"type": "FactSet", "facts": [
            {"title": "آنکال قبلی", "value": "${previousOncall}"},
            {"title": "آنکال جدید", "value": "${currentOncall}"},
            {"title": "شروع", "value": "${startDate}"},
            {"title": "پایان", "value": "${endDate}"}
          ]}
        ]
      }
  → Microsoft Teams (send_chat_message)
    ChatId: DM_WITH_ONCALL
    Content: "سلام! شیفت آنکال این هفته با شماست. راهنما: ${runbookUrl}"

۱۰. ایجاد خودکار تیم برای پروژه

ایجاد تیم و کانال‌ها برای هر پروژه جدید:

code
Webhook (پروژه جدید از سیستم PM)
  → Microsoft Teams (create_team)
    DisplayName: "پروژه: ${projectName}"
    Description: "${projectDescription}"
    Visibility: private
  → Microsoft Teams (create_channel)
    DisplayName: "طراحی"
    Description: "بحث‌های طراحی و UX/UI"
  → Microsoft Teams (create_channel)
    DisplayName: "توسعه"
    Description: "بحث‌های فنی و کد"
  → Microsoft Teams (create_channel)
    DisplayName: "تست"
    Description: "گزارش باگ و QA"
  → Loop (اعضای پروژه)
    → Microsoft Teams (add_member)
      UserId: ${memberEmail}
      Role: ${isLead ? 'owner' : 'member'}
  → Microsoft Teams (send_message)
    ChannelId: GENERAL_CHANNEL_ID
    Content: "تیم پروژه ${projectName} آماده است! بیایید شروع کنیم."

۱۱. ارسال گزارش فایل خودکار

تولید و ارسال گزارش Excel/PDF به کانال:

code
Schedule (اول هر ماه)
  → Database (داده‌های ماهانه)
  → Code (ساخت Excel/CSV)
  → Microsoft Teams (upload_file)
    TeamId: FINANCE_TEAM_ID
    ChannelId: REPORTS_CHANNEL_ID
    FileName: "report-${year}-${month}.xlsx"
  → Microsoft Teams (send_message)
    Content: "گزارش مالی ${monthName} آماده شد. فایل در تب Files موجود است."

نکات حرفه‌ای

نکات حرفه‌ای

۱. Adaptive Cards - سیستم پیام‌های تعاملی

Adaptive Cards قدرتمندترین روش نمایش اطلاعات در Teams است:

json
{
  "type": "AdaptiveCard",
  "version": "1.4",
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "body": [
    {
      "type": "TextBlock",
      "text": "عنوان پیام",
      "weight": "bolder",
      "size": "large",
      "color": "accent"
    },
    {
      "type": "FactSet",
      "facts": [
        {"title": "وضعیت", "value": "فعال"},
        {"title": "تاریخ", "value": "1403/10/25"}
      ]
    },
    {
      "type": "ColumnSet",
      "columns": [
        {
          "type": "Column",
          "width": "auto",
          "items": [
            {"type": "Image", "url": "https://...", "size": "small"}
          ]
        },
        {
          "type": "Column",
          "width": "stretch",
          "items": [
            {"type": "TextBlock", "text": "نام کاربر", "weight": "bolder"},
            {"type": "TextBlock", "text": "توسعه‌دهنده ارشد", "isSubtle": true}
          ]
        }
      ]
    },
    {
      "type": "Input.Text",
      "id": "comment",
      "placeholder": "نظر خود را بنویسید..."
    }
  ],
  "actions": [
    {"type": "Action.Submit", "title": "تایید", "style": "positive"},
    {"type": "Action.Submit", "title": "رد", "style": "destructive"},
    {"type": "Action.OpenUrl", "title": "مشاهده", "url": "https://..."},
    {"type": "Action.ShowCard", "title": "جزئیات بیشتر",
      "card": {
        "type": "AdaptiveCard",
        "body": [{"type": "TextBlock", "text": "اطلاعات تکمیلی..."}]
      }
    }
  ]
}

۲. Adaptive Cards Designer

قبل از کدنویسی، کارت را در محیط بصری طراحی کنید:

code
https://adaptivecards.io/designer/
  • Host App: Microsoft Teams را انتخاب کنید
  • JSON خروجی را مستقیماً در n8n استفاده کنید
  • پیش‌نمایش دقیق در Teams را مشاهده کنید
  • نسخه Card را روی 1.4 یا 1.5 تنظیم کنید

۳. @Mention کاربران در پیام

برای منشن کردن کاربر در پیام HTML:

html
<at id="0">نام کاربر</at>

<!-- در body درخواست API: -->
{
  "body": {
    "contentType": "html",
    "content": "<at id=\"0\">علی احمدی</at> لطفا بررسی کنید."
  },
  "mentions": [
    {
      "id": 0,
      "mentionText": "علی احمدی",
      "mentioned": {
        "user": {
          "id": "USER_ID",
          "displayName": "علی احمدی",
          "userIdentityType": "aadUser"
        }
      }
    }
  ]
}

۴. فرمت‌بندی HTML در Teams

Teams از زیرمجموعه‌ای از HTML پشتیبانی می‌کند:

html
<b>Bold</b>                  → متن ضخیم
<i>Italic</i>                → متن مورب
<s>Strikethrough</s>         → خط خورده
<h1>Header 1</h1>            → سرتیتر (h1-h6)
<ul><li>Item</li></ul>       → لیست نقطه‌ای
<ol><li>Item</li></ol>       → لیست شماره‌ای
<a href="url">Link</a>       → لینک
<pre>Code block</pre>         → بلوک کد
<code>Inline code</code>     → کد خطی
<blockquote>Quote</blockquote> → نقل قول
<table><tr><td></td></tr></table> → جدول
<img src="url" alt=""/>       → تصویر
<br>                          → خط جدید
<hr>                          → خط جداکننده

۵. Importance (اولویت پیام)

سطوح اولویت پیام در Teams:

code
normal:  پیام عادی بدون اعلان خاص
high:    پیام مهم با اعلان Priority
urgent:  پیام فوری با اعلان مکرر هر 2 دقیقه تا 20 دقیقه

از urgent فقط برای Incidentها و هشدارهای بحرانی استفاده کنید.

۶. Incoming Webhook با Adaptive Card

ارسال Adaptive Card از طریق Webhook (بدون OAuth):

json
{
  "type": "message",
  "attachments": [
    {
      "contentType": "application/vnd.microsoft.card.adaptive",
      "contentUrl": null,
      "content": {
        "type": "AdaptiveCard",
        "version": "1.4",
        "body": [
          {"type": "TextBlock", "text": "اعلان از سیستم خارجی", "weight": "bolder"}
        ]
      }
    }
  ]
}

۷. Microsoft Graph API Explorer

قبل از پیاده‌سازی، API را در محیط تست اجرا کنید:

code
https://developer.microsoft.com/graph/graph-explorer
  • با حساب Microsoft وارد شوید
  • APIهای مختلف Teams را تست کنید
  • پاسخ JSON را مشاهده و بررسی کنید

۸. OData Filter برای لیست‌ها

فیلتر کردن نتایج List Teams و List Channels:

code
// فیلتر تیم‌ها بر اساس نام
$filter=displayName eq 'DevOps'

// فیلتر کانال‌های Standard
$filter=membershipType eq 'standard'

// جستجو در نام
$filter=startsWith(displayName, 'پروژه')

// Select فیلدهای خاص
$select=id,displayName,description

// ترتیب
$orderby=displayName asc

// صفحه‌بندی
$top=50&$skip=0

۹. محدودیت‌های مهم Microsoft Teams API

code
پیام متنی:           حدود 28KB
Adaptive Card:        28KB (شامل JSON)
فایل آپلود:          250MB per file
اعضای تیم:           25,000 نفر
کانال‌های تیم:         1000 (شامل حذف‌شده‌ها)
کانال‌های Private:     30 per team
اعضای چت گروهی:      250 نفر
Mentions per Message:  50 عدد
Webhooks per Channel:  بدون محدودیت رسمی
Rate Limit:           متغیر (معمولا 2000 req/10 sec)

۱۰. تفاوت Delegated و Application Permissions

code
Delegated Permissions:
  - عملیات به نیابت از کاربر
  - نیاز به OAuth2 Login
  - محدود به دسترسی‌های کاربر
  - مناسب برای: عملیات کاربر-محور

Application Permissions:
  - عملیات بدون کاربر (Background/Service)
  - از Client Credentials Flow استفاده می‌کند
  - دسترسی سطح سازمان
  - نیاز به Admin Consent
  - مناسب برای: Cron Jobs، اتوماسیون بدون تعامل کاربر

۱۱. Thread و Reply برای مکالمات سازمان‌یافته

از Thread برای نظم‌دهی بحث‌ها استفاده کنید:

code
// ارسال پیام اصلی
Microsoft Teams (send_message) → خروجی: messageId

// پاسخ در Thread
Microsoft Teams (reply_to_message)
  messageId: {{$json.id}}
  content: "پاسخ در Thread"

// نکته: Thread replies هم از HTML و Adaptive Card پشتیبانی می‌کنند

۱۲. Actionable Messages با Webhook

پیام‌های تعاملی با دکمه و لینک از طریق Webhook:

json
{
  "@type": "MessageCard",
  "@context": "http://schema.org/extensions",
  "summary": "خلاصه پیام",
  "themeColor": "0076D7",
  "title": "عنوان کارت",
  "sections": [
    {
      "activityTitle": "رویداد جدید",
      "facts": [
        {"name": "نوع", "value": "هشدار"},
        {"name": "زمان", "value": "10:30"}
      ],
      "markdown": true
    }
  ],
  "potentialAction": [
    {
      "@type": "OpenUri",
      "name": "مشاهده جزئیات",
      "targets": [{"os": "default", "uri": "https://..."}]
    },
    {
      "@type": "ActionCard",
      "name": "پاسخ",
      "inputs": [{"@type": "TextInput", "id": "comment", "title": "نظر شما"}],
      "actions": [{"@type": "HttpPOST", "name": "ارسال", "target": "https://webhook-url"}]
    }
  ]
}

۱۳. Error Handling حرفه‌ای

code
Microsoft Teams (send_message)
  → On Error: Continue
  → IF (خطا)
    → Switch (error code)
      → 401: Refresh Token → Retry
      → 403: Log "Permission denied" → Alert Admin
      → 404: Log "Team/Channel not found" → Skip
      → 429: Wait (Retry-After header) → Retry
      → Default: Log Error → Fallback (Email/Webhook)

۱۴. Batch Operations برای عملکرد بهتر

برای عملیات روی چندین آیتم:

code
// به جای ارسال جداگانه به 10 کانال:
// از Microsoft Graph Batch API استفاده کنید
POST https://graph.microsoft.com/v1.0/$batch
{
  "requests": [
    {"id": "1", "method": "POST", "url": "/teams/{id}/channels/{id}/messages", "body": {...}},
    {"id": "2", "method": "POST", "url": "/teams/{id}/channels/{id}/messages", "body": {...}}
  ]
}
// حداکثر 20 درخواست در هر Batch

۱۵. تنظیمات جلسه آنلاین پیشرفته

json
{
  "subject": "جلسه Sprint Review",
  "startDateTime": "2025-01-15T10:00:00+03:30",
  "endDateTime": "2025-01-15T11:00:00+03:30",
  "lobbyBypassSettings": {
    "scope": "organization",
    "isDialInBypassEnabled": true
  },
  "isEntryExitAnnounced": true,
  "allowedPresenters": "roleIsPresenter",
  "audioConferencing": {
    "tollNumber": "+1-xxx-xxx-xxxx"
  }
}

۱۶. متن فارسی RTL در Teams

Teams به صورت خودکار متن RTL فارسی را تشخیص می‌دهد:

html
<!-- فرمت HTML برای متن‌های فارسی-انگلیسی ترکیبی -->
<div dir="rtl">
  <b>گزارش وضعیت سرویس</b><br>
  سرویس API: <span style="color:green">فعال</span><br>
  سرویس Database: <span style="color:red">غیرفعال</span><br>
  آخرین بررسی: 14:30
</div>

۱۷. PowerAutomate vs n8n برای Teams

code
n8n مزایا:
  + Self-hosted (حاکمیت داده)
  + بدون محدودیت اجرا
  + یکپارچه‌سازی با +400 سرویس
  + رایگان و Open-source
  + سرعت بالاتر در اجرا

Power Automate مزایا:
  + یکپارچه‌سازی عمیق‌تر با Microsoft 365
  + Trigger‌های بیشتر Teams
  + بدون نیاز به سرور

توصیه: از n8n برای اتوماسیون‌های پیچیده و Cross-platform استفاده کنید.

رفع مشکلات

خطاهای رایج و راه‌حل‌ها

۱. خطای "Authorization_RequestDenied" (403)

علت: App Registration دسترسی (Permission) لازم را ندارد

راه‌حل

  • به Azure Portal > App registrations > API permissions بروید
  • Permission مورد نیاز را اضافه کنید (مثل ChannelMessage.Send)
  • مهم: حتما Grant admin consent را بزنید
  • بدون Admin Consent، Permission‌ها فعال نمی‌شوند
  • برای Application Permissions حتما Admin Consent لازم است
  • لیست Permission‌های مورد نیاز هر عملیات در مستندات Microsoft Graph موجود است

۲. خطای "InvalidAuthenticationToken" (401)

علت: Token نامعتبر، منقضی شده یا Client Secret اشتباه

راه‌حل

  • مطمئن شوید Client Secret منقضی نشده باشد (بررسی تاریخ انقضا در Azure)
  • Client ID و Tenant ID صحیح باشند
  • Credential را در n8n حذف و مجدد ایجاد کنید
  • مجدد OAuth2 Authorization را انجام دهید (Connect)
  • اگر Multi-tenant است، Tenant ID را common قرار دهید

۳. خطای "TeamNotFound" یا "ResourceNotFound" (404)

علت: Team ID یا Channel ID اشتباه، یا تیم/کانال حذف شده

راه‌حل

  • از عملیات list_teams و list_channels برای دریافت ID صحیح استفاده کنید
  • Team ID فرمت GUID دارد: مثل xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  • مطمئن شوید تیم آرشیو یا حذف نشده باشد
  • کاربر احراز هویت شده باید عضو تیم باشد
  • برای کانال‌های Private، کاربر باید عضو کانال باشد

۴. خطای "Forbidden: BotNotInConversationRoster"

علت: App به تیم یا چت اضافه نشده

راه‌حل

  • برای ارسال پیام در کانال، App باید به تیم نصب شده باشد
  • از Teams Admin Center: Manage apps > اپلیکیشن را به تیم اضافه کنید
  • یا از Microsoft Graph: POST /teams/{teamId}/installedApps
  • برای چت‌ها: App باید در چت نصب شده باشد

۵. خطای "ItemNotFound" هنگام آپلود فایل

علت: مسیر SharePoint یا Drive ID نادرست

راه‌حل

  • ابتدا Drive ID کانال را دریافت کنید:
code
GET /teams/{teamId}/channels/{channelId}/filesFolder
  • مطمئن شوید SharePoint site فعال و قابل دسترسی باشد
  • مسیر پوشه را بررسی کنید (از / شروع نمی‌شود)
  • دسترسی Files.ReadWrite.All فعال باشد

۶. خطای "ThrottledRequest" (429 - Rate Limit)

علت: تعداد درخواست‌ها از محدودیت Microsoft Graph عبور کرده

راه‌حل

  • محدودیت‌های Microsoft Graph:
  • Per-App: 2000 request/10 seconds
  • Per-App per Tenant: 200,000 request/10 minutes
  • Per-Thread: متغیر بسته به عملیات
  • Header Retry-After مدت انتظار (ثانیه) را مشخص می‌کند
  • از Wait Node استفاده کنید:
code
Loop → Teams → Wait (2 seconds) → Next
  • پیام‌ها را Batch کنید و با فاصله ارسال کنید
  • از Exponential Backoff استفاده کنید

۷. خطای "BadRequest" هنگام ارسال Adaptive Card

علت: ساختار JSON کارت نادرست

راه‌حل

  • از [Adaptive Cards Designer](https://adaptivecards.io/designer/) برای طراحی و تست استفاده کنید
  • version باید 1.4 یا بالاتر باشد (Teams از 1.5 پشتیبانی می‌کند)
  • Card باید در attachment با contentType مناسب ارسال شود:
json
{
    "contentType": "application/vnd.microsoft.card.adaptive",
    "content": { "type": "AdaptiveCard", "version": "1.4", "body": [...] }
  }
  • مطمئن شوید JSON معتبر است (از JSON Validator استفاده کنید)
  • حداکثر حجم Card: 28KB

۸. خطای "NameAlreadyExists" هنگام ایجاد تیم/کانال

علت: نام تیم یا کانال تکراری است

راه‌حل

  • نام تیم/کانال باید در سازمان/تیم یکتا باشد
  • از پیشوند تاریخ یا شناسه استفاده کنید: پروژه-${projectId}-${date}
  • قبل از ایجاد، وجود نام را با List Teams/Channels بررسی کنید
  • کانال‌های حذف شده ممکن است هنوز نام را اشغال کنند (Soft Delete 30 روزه)

۹. خطای "InsufficientPrivileges" هنگام اضافه کردن عضو

علت: کاربر جاری Owner تیم نیست

راه‌حل

  • فقط Owner‌های تیم می‌توانند عضو جدید اضافه کنند
  • با Application Permission و Admin Consent این محدودیت برطرف می‌شود
  • از TeamMember.ReadWrite.All Permission استفاده کنید
  • برای Guest Invitation: دسترسی Guest Inviter در Azure AD لازم است

۱۰. Webhook ارسال پیام نمی‌کند

علت: URL نامعتبر یا Webhook غیرفعال شده

راه‌حل

  • Webhook URL را مجدد از Teams Channel Settings کپی کنید
  • مطمئن شوید Incoming Webhook connector هنوز فعال است
  • Content-Type باید application/json باشد
  • Body حداقل باید شامل text یا attachments باشد:
json
{
    "text": "پیام ساده",
    "@type": "MessageCard",
    "summary": "خلاصه"
  }
  • برای Adaptive Card در Webhook از فرمت خاص استفاده کنید
اشتراک‌گذاری:

آیا این مستندات مفید بود؟