Microsoft Teams

​

Plugin مضمّن

openclaw plugins install @openclaw/msteams

openclaw plugins install ./path/to/local/msteams-plugin

​

الإعداد السريع

npm install -g @microsoft/teams.cli@preview
teams login
teams status   # تحقّق من تسجيل دخولك واعرض معلومات المستأجر

# إعداد لمرة واحدة (عنوان URL دائم عبر الجلسات):
devtunnel create my-openclaw-bot --allow-anonymous
devtunnel port create my-openclaw-bot -p 3978 --protocol auto

# في كل جلسة تطوير:
devtunnel host my-openclaw-bot
# نقطة النهاية: https://<tunnel-id>.devtunnels.ms/api/messages

teams app create \
  --name "OpenClaw" \
  --endpoint "https://<your-tunnel-url>/api/messages"

{
  channels: {
    msteams: {
      enabled: true,
      appId: "<CLIENT_ID>",
      appPassword: "<CLIENT_SECRET>",
      tenantId: "<TENANT_ID>",
      webhook: { port: 3978, path: "/api/messages" },
    },
  },
}

teams app get <teamsAppId> --install-link

teams app doctor <teamsAppId>

​

الأهداف

• تواصل مع OpenClaw عبر الرسائل المباشرة أو الدردشات الجماعية أو القنوات في Teams.
• حافظ على حتمية التوجيه: تعود الردود دائمًا إلى القناة التي وردت منها.
• استخدم سلوكًا آمنًا للقنوات افتراضيًا (تكون الإشارات مطلوبة ما لم يُضبط خلاف ذلك).

​

عمليات كتابة التكوين

{
  channels: { msteams: { configWrites: false } },
}

​

التحكم في الوصول (الرسائل المباشرة + المجموعات)

• الإعداد الافتراضي: channels.msteams.dmPolicy = "pairing". يُتجاهل المرسلون غير المعروفين حتى تتم الموافقة عليهم.
• يجب أن يستخدم channels.msteams.allowFrom معرّفات كائنات AAD ثابتة أو مجموعات وصول ثابتة للمرسلين مثل accessGroup:core-team.
• لا تعتمد على مطابقة UPN/اسم العرض في قوائم السماح؛ فقد تتغير. يعطّل OpenClaw المطابقة المباشرة للأسماء افتراضيًا؛ فعّلها باستخدام channels.msteams.dangerouslyAllowNameMatching: true.
• يمكن للمعالج تحويل الأسماء إلى معرّفات عبر Microsoft Graph عندما تسمح بيانات الاعتماد بذلك.

• الإعداد الافتراضي: channels.msteams.groupPolicy = "allowlist" (محظور ما لم تُضف groupAllowFrom). يمكن لـ channels.defaults.groupPolicy تجاوز الإعداد الافتراضي المشترك عندما لا يكون channels.msteams.groupPolicy مضبوطًا.
• يتحكم channels.msteams.groupAllowFrom في المرسلين أو مجموعات الوصول الثابتة للمرسلين الذين يمكنهم التشغيل في الدردشات الجماعية/القنوات (ويعود إلى channels.msteams.allowFrom عند عدم الضبط).
• اضبط groupPolicy: "open" للسماح لأي عضو (مع بقاء اشتراط الإشارة افتراضيًا).
• لحظر جميع القنوات، اضبط channels.msteams.groupPolicy: "disabled".

{
  channels: {
    msteams: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["00000000-0000-0000-0000-000000000000", "accessGroup:core-team"],
    },
  },
}

• حدّد نطاق الردود الجماعية/ردود القنوات بإدراج الفرق والقنوات ضمن channels.msteams.teams.
• استخدم معرّفات محادثات Teams الثابتة من روابط Teams بوصفها مفاتيح، وليس أسماء العرض القابلة للتغيير (راجع معرّفات الفريق والقناة).
• عند وجود groupPolicy="allowlist" وقائمة سماح للفرق، لا تُقبل إلا الفرق/القنوات المدرجة (مع اشتراط الإشارة).
• يقبل معالج التكوين إدخالات Team/Channel ويخزّنها لك.
• عند بدء التشغيل، يحوّل OpenClaw أسماء الفرق/القنوات وأسماء قائمة سماح المستخدمين إلى معرّفات (عندما تسمح أذونات Graph بذلك) ويسجّل المطابقة. تُحفظ الأسماء التي تعذر تحويلها كما كُتبت، لكنها تُتجاهل في التوجيه ما لم يُضبط channels.msteams.dangerouslyAllowNameMatching: true.

{
  channels: {
    msteams: {
      groupPolicy: "allowlist",
      teams: {
        "My Team": {
          channels: {
            General: { requireMention: true },
          },
        },
      },
    },
  },
}

​

المصادقة الموحّدة (شهادة بالإضافة إلى هوية مُدارة)

​

الخيار أ: المصادقة المستندة إلى شهادة

1. ولّد شهادة أو احصل عليها (بتنسيق PEM مع مفتاح خاص).
2. Entra ID ← App Registration ← Certificates & secrets ← Certificates ← ارفع الشهادة العامة.

{
  channels: {
    msteams: {
      enabled: true,
      appId: "<APP_ID>",
      tenantId: "<TENANT_ID>",
      authType: "federated",
      certificatePath: "/path/to/cert.pem",
      webhook: { port: 3978, path: "/api/messages" },
    },
  },
}

• MSTEAMS_AUTH_TYPE=federated
• MSTEAMS_CERTIFICATE_PATH=/path/to/cert.pem

​

الخيار ب: Azure Managed Identity

1. تحتوي حاوية الروبوت/الجهاز الافتراضي على هوية مُدارة (معيّنة من النظام أو المستخدم).
2. تربط بيانات اعتماد هوية موحّدة الهوية المُدارة بتسجيل تطبيق Entra ID.
3. في وقت التشغيل، يستخدم OpenClaw ‏@azure/identity للحصول على الرموز المميزة من نقطة نهاية Azure IMDS.
4. يُمرر الرمز المميز إلى Teams SDK لمصادقة الروبوت.

• بنية Azure التحتية مع تمكين الهوية المُدارة (هوية حمل العمل في AKS أو App Service أو VM).
• بيانات اعتماد هوية موحّدة مُنشأة في تسجيل تطبيق Entra ID.
• وصول الشبكة إلى IMDS ‏(169.254.169.254:80) من الحاوية/VM.

{
  channels: {
    msteams: {
      enabled: true,
      appId: "<APP_ID>",
      tenantId: "<TENANT_ID>",
      authType: "federated",
      useManagedIdentity: true,
      webhook: { port: 3978, path: "/api/messages" },
    },
  },
}

• MSTEAMS_AUTH_TYPE=federated
• MSTEAMS_USE_MANAGED_IDENTITY=true
• MSTEAMS_MANAGED_IDENTITY_CLIENT_ID=<client-id> (للهوية المعيّنة من المستخدم فقط)

​

إعداد هوية حمل العمل في AKS

1. فعّل هوية حمل العمل في مجموعة AKS.
2. أنشئ بيانات اعتماد هوية موحّدة في تسجيل تطبيق Entra ID:
   az ad app federated-credential create --id <APP_OBJECT_ID> --parameters '{
     "name": "my-bot-workload-identity",
     "issuer": "<AKS_OIDC_ISSUER_URL>",
     "subject": "system:serviceaccount:<NAMESPACE>:<SERVICE_ACCOUNT>",
     "audiences": ["api://AzureADTokenExchange"]
   }'
   
3. أضف تعليقًا توضيحيًا إلى حساب خدمة Kubernetes باستخدام معرّف عميل التطبيق:
   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: my-bot-sa
     annotations:
       azure.workload.identity/client-id: "<APP_CLIENT_ID>"
   
4. أضف تسمية إلى الحاوية لحقن هوية حمل العمل:
   metadata:
     labels:
       azure.workload.identity/use: "true"
   
5. اسمح بالوصول عبر الشبكة إلى IMDS ‏(169.254.169.254): إذا كنت تستخدم NetworkPolicy، فأضف قاعدة خروج لـ 169.254.169.254/32 على المنفذ 80.

​

مقارنة أنواع المصادقة

​

التطوير المحلي (إنشاء نفق)

# إعداد لمرة واحدة:
devtunnel create my-openclaw-bot --allow-anonymous
devtunnel port create my-openclaw-bot -p 3978 --protocol auto

# كل جلسة تطوير:
devtunnel host my-openclaw-bot

teams app update <teamsAppId> --endpoint "https://<new-url>/api/messages"

​

اختبار الروبوت

teams app doctor <teamsAppId>

1. ثبّت تطبيق Microsoft Teams (رابط التثبيت من teams app get <id> --install-link).
2. ابحث عن الروبوت في Microsoft Teams وأرسل إليه رسالة مباشرة.
3. تحقق من سجلات Gateway بحثًا عن النشاط الوارد.

​

متغيرات البيئة

​

إجراء معلومات العضو

• أذونات RSC ‏ChannelSettings.Read.Group وTeamMember.Read.Group (مضمّنة بالفعل في البيان الموصى به).

​

سياق السجل

• يتحكم channels.msteams.historyLimit في عدد رسائل القنوات/المجموعات الحديثة التي تُضمّن في الموجّه. ويعود إلى messages.groupChat.historyLimit عند عدم تعيينه، ثم تكون القيمة الافتراضية 50. عيّن 0 للتعطيل.
• يُرشّح سجل سلسلة المحادثة الذي جرى جلبه وفق قوائم المرسلين المسموح لهم (allowFrom / groupAllowFrom)؛ لذلك لا تتضمن تهيئة سياق السلسلة إلا رسائل المرسلين المسموح لهم.
• يُمرّر سياق المرفقات المقتبسة (المحلّل من HTML الخاص بمخطط Skype Reply ضمن مرفقات الرد نفسه) دون تصفية؛ وتطبّق تهيئة سجل السلسلة فقط مرشّح قائمة المرسلين المسموح لهم حاليًا.
• يمكن تقييد سجل الرسائل المباشرة باستخدام channels.msteams.dmHistoryLimit (أدوار المستخدم). التجاوزات الخاصة بكل مستخدم: channels.msteams.dms["<user_id>"].historyLimit.

​

أذونات RSC الحالية في Microsoft Teams (البيان)

• ChannelMessage.Read.Group (Application) - تلقي جميع رسائل القناة دون @mention
• ChannelMessage.Send.Group (Application)
• Member.Read.Group (Application)
• Owner.Read.Group (Application)
• ChannelSettings.Read.Group (Application)
• TeamMember.Read.Group (Application)
• TeamSettings.Read.Group (Application)

• ChatMessage.Read.Chat (Application) - تلقي جميع رسائل الدردشة الجماعية دون @mention

teams app rsc add <teamsAppId> ChannelMessage.Read.Group --type Application

​

مثال على بيان Microsoft Teams (منقّح)

{
  $schema: "https://developer.microsoft.com/en-us/json-schemas/teams/v1.23/MicrosoftTeams.schema.json",
  manifestVersion: "1.23",
  version: "1.0.0",
  id: "00000000-0000-0000-0000-000000000000",
  name: { short: "OpenClaw" },
  developer: {
    name: "Your Org",
    websiteUrl: "https://example.com",
    privacyUrl: "https://example.com/privacy",
    termsOfUseUrl: "https://example.com/terms",
  },
  description: { short: "OpenClaw in Teams", full: "OpenClaw in Teams" },
  icons: { outline: "outline.png", color: "color.png" },
  accentColor: "#5B6DEF",
  bots: [
    {
      botId: "11111111-1111-1111-1111-111111111111",
      scopes: ["personal", "team", "groupChat"],
      isNotificationOnly: false,
      supportsCalling: false,
      supportsVideo: false,
      supportsFiles: true,
    },
  ],
  webApplicationInfo: {
    id: "11111111-1111-1111-1111-111111111111",
  },
  authorization: {
    permissions: {
      resourceSpecific: [
        { name: "ChannelMessage.Read.Group", type: "Application" },
        { name: "ChannelMessage.Send.Group", type: "Application" },
        { name: "Member.Read.Group", type: "Application" },
        { name: "Owner.Read.Group", type: "Application" },
        { name: "ChannelSettings.Read.Group", type: "Application" },
        { name: "TeamMember.Read.Group", type: "Application" },
        { name: "TeamSettings.Read.Group", type: "Application" },
        { name: "ChatMessage.Read.Chat", type: "Application" },
      ],
    },
  },
}

​

محاذير البيان (الحقول الإلزامية)

• يجب أن يتطابق bots[].botId مع معرّف تطبيق Azure Bot.
• يجب أن يتطابق webApplicationInfo.id مع معرّف تطبيق Azure Bot.
• يجب أن يتضمن bots[].scopes الأسطح التي تخطط لاستخدامها (personal، team، groupChat).
• يلزم bots[].supportsFiles: true لمعالجة الملفات في النطاق الشخصي.
• يجب أن يتضمن authorization.permissions.resourceSpecific أذونات قراءة القنوات والإرسال إليها لحركة مرور القنوات.

​

تحديث تطبيق حالي

# نزّل البيان وعدّله ثم أعد تحميله
teams app manifest download <teamsAppId> manifest.json
# عدّل manifest.json محليًا...
teams app manifest upload manifest.json <teamsAppId>
# يُزاد الإصدار تلقائيًا إذا تغير المحتوى

​

الإمكانات: RSC فقط مقارنةً بـ Graph

​

باستخدام RSC الخاص بـ Microsoft Teams فقط (التطبيق مثبت، دون أذونات Graph API)

• قراءة المحتوى النصي لرسائل القناة.
• إرسال محتوى نصي في رسائل القناة.
• تلقي مرفقات الملفات الشخصية (الرسائل المباشرة).

• محتوى الصور أو الملفات في القنوات/المجموعات (لا تتضمن الحمولة إلا جزء HTML نائبًا).
• تنزيل المرفقات المخزنة في SharePoint/OneDrive.
• قراءة سجل الرسائل خارج حدث Webhook المباشر.

​

باستخدام RSC الخاص بـ Microsoft Teams + أذونات تطبيق Microsoft Graph

• تنزيل المحتوى المستضاف (الصور الملصقة في الرسائل).
• تنزيل مرفقات الملفات المخزنة في SharePoint/OneDrive.
• قراءة سجل رسائل القنوات/الدردشات عبر Graph.

​

RSC مقارنةً بـ Graph API

​

الوسائط والسجل الممكّنان عبر Graph

1. Entra ID (Azure AD) App Registration → أضف Application permissions الخاصة بـ Graph:
   • ChannelMessage.Read.All لمرفقات القنوات وسجل القنوات.
   • Chat.Read.All لمرفقات المحادثات الجماعية وسجل المحادثات الجماعية.
   • Files.Read.All عندما يجب تنزيل وحدات بايت المرفقات من مساحة تخزين SharePoint/OneDrive؛ لا تحتاج إليها الإعدادات المخصصة للسجل فقط.
2. نفّذ Grant admin consent للمستأجر.
3. ارفع manifest version لتطبيق Teams، وأعد تحميله، ثم أعد تثبيت التطبيق في Teams.
4. أغلق Teams بالكامل ثم أعد تشغيله لمسح بيانات تعريف التطبيق المخزنة مؤقتًا.

​

استرداد ملفات القنوات/المجموعات (graphMediaFallback)

{
  channels: {
    msteams: {
      graphMediaFallback: true,
    },
  },
}

​

القيود المعروفة

​

انتهاء مهلة Webhook

• إعادة Teams محاولة إرسال الرسالة (ما يسبب تكرارات).
• فقدان الردود.

​

دعم سحابة Teams وعنوان URL للخدمة

• يحدد channels.msteams.cloud الإعداد المسبق لسحابة Teams SDK للمصادقة، والتحقق من JWT، وخدمات الرموز، ونطاق Graph.
• يحدد channels.msteams.serviceUrl حد نقطة نهاية Bot Connector المستخدم للتحقق من مراجع المحادثات المخزنة قبل عمليات الإرسال والتعديل والحذف والبطاقات والاستطلاعات ورسائل الموافقة على الملفات والردود طويلة التشغيل الموضوعة في قائمة الانتظار. وهو مطلوب لسُحب USGov وDoD في SDK. بالنسبة إلى China/21Vianet، يستخدم OpenClaw إعداد SDK المسبق China ولا يقبل عناوين URL المخزنة/المكوّنة للخدمة إلا على مضيفات قنوات Azure China Bot Framework.

{
  "channels": {
    "msteams": {
      "serviceUrl": "https://smba.infra.gcc.teams.microsoft.com/teams"
    }
  }
}

{
  "channels": {
    "msteams": {
      "cloud": "USGov",
      "serviceUrl": "https://smba.infra.gov.teams.microsoft.us/teams"
    }
  }
}

​

التنسيق

• يعمل التنسيق الأساسي: العريض، المائل، code، والروابط.
• قد لا يُعرض Markdown المعقد (الجداول والقوائم المتداخلة) بصورة صحيحة.
• تُدعم Adaptive Cards للاستطلاعات وعمليات إرسال العروض الدلالية (انظر أدناه).

​

الإعداد

• channels.msteams.enabled: تمكين/تعطيل القناة.
• channels.msteams.appId، channels.msteams.appPassword، channels.msteams.tenantId: بيانات اعتماد الروبوت.
• channels.msteams.cloud: بيئة Teams SDK السحابية (Public، أو USGov، أو USGovDoD، أو China؛ الافتراضي Public). اضبطها باستخدام serviceUrl لسُحب USGov/DoD الخاصة بـ SDK؛ تستخدم الصين الإعداد المسبق لـ SDK ومراجع محادثات Azure China Bot Framework المخزنة، مع تعطيل الأدوات المساعدة المدعومة من Graph حتى يتوفر توجيه Azure China Graph.
• channels.msteams.serviceUrl: حد عنوان URL لخدمة Bot Connector للعمليات الاستباقية في SDK. تستخدم السحابة العامة الإعداد الافتراضي لـ SDK؛ اضبطه لـ GCC ‏(https://smba.infra.gcc.teams.microsoft.com/teams) أو GCC High أو DoD. تقبل الصين مضيفي قنوات Azure China Bot Framework عندما يأتي مرجع المحادثة المخزن من Teams الذي تديره 21Vianet.
• channels.msteams.webhook.port (الافتراضي 3978).
• channels.msteams.webhook.path (الافتراضي /api/messages).
• channels.msteams.dmPolicy: pairing | allowlist | open | disabled (الافتراضي pairing).
• channels.msteams.allowFrom: قائمة السماح للرسائل المباشرة (يُوصى بمعرّفات كائنات AAD). يحوّل المعالج الأسماء إلى معرّفات أثناء الإعداد عندما يتوفر الوصول إلى Graph.
• channels.msteams.dangerouslyAllowNameMatching: مفتاح تبديل للطوارئ لإعادة تمكين مطابقة UPN/اسم العرض القابلة للتغيير والتوجيه المباشر بأسماء الفرق/القنوات.
• channels.msteams.textChunkLimit: حجم تجزئة النص الصادر بالأحرف (الافتراضي 4000، مع حد أقصى صارم يبلغ 4000 بصرف النظر عن أي قيمة مُعدّة أعلى).
• channels.msteams.streaming.chunkMode: length (الافتراضي) أو newline للتقسيم عند الأسطر الفارغة (حدود الفقرات) قبل التجزئة حسب الطول.
• channels.msteams.mediaAllowHosts: قائمة السماح لمضيفي المرفقات الواردة (الإعداد الافتراضي هو نطاقات Microsoft/Teams: ‏Graph وSharePoint/OneDrive وTeams CDN وBot Framework وAzure Media Services).
• channels.msteams.mediaAuthAllowHosts: قائمة السماح بإرفاق ترويسات Authorization عند إعادة محاولة جلب الوسائط (الإعداد الافتراضي هو مضيفو Graph وBot Framework).
• channels.msteams.graphMediaFallback: الاشتراك في عمليات بحث Graph عن الرسائل عندما لا يتضمن HTML الخاص بالقناة/المجموعة علامات الملفات (الافتراضي false؛ راجع استرداد ملفات القناة/المجموعة).
• channels.msteams.mediaMaxMb: تجاوز حد حجم الوسائط لكل قناة بالميغابايت. يعود إلى agents.defaults.mediaMaxMb عند عدم ضبطه.
• channels.msteams.requireMention: اشتراط الإشارة بـ @ في القنوات/المجموعات (الافتراضي true).
• channels.msteams.replyStyle: thread | top-level (راجع نمط الرد).
• channels.msteams.teams.<teamId>.replyStyle: تجاوز لكل فريق.
• channels.msteams.teams.<teamId>.requireMention: تجاوز لكل فريق.
• channels.msteams.teams.<teamId>.tools: تجاوزات سياسة الأدوات الافتراضية لكل فريق (allow/deny/alsoAllow) المستخدمة عند غياب تجاوز للقناة.
• channels.msteams.teams.<teamId>.toolsBySender: تجاوزات سياسة الأدوات الافتراضية لكل فريق ولكل مُرسِل (حرف البدل "*" مدعوم).
• channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle: تجاوز لكل قناة.
• channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention: تجاوز لكل قناة.
• channels.msteams.teams.<teamId>.channels.<conversationId>.tools: تجاوزات سياسة الأدوات لكل قناة (allow/deny/alsoAllow).
• channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender: تجاوزات سياسة الأدوات لكل قناة ولكل مُرسِل (حرف البدل "*" مدعوم).
• يجب أن تستخدم مفاتيح toolsBySender بادئات صريحة: channel:، وid:، وe164:، وusername:، وname: (لا تزال المفاتيح القديمة غير المسبوقة ببادئة تُعيَّن إلى id: فقط).
• channels.msteams.authType: نوع المصادقة - "secret" (الافتراضي) أو "federated".
• channels.msteams.certificatePath: مسار ملف شهادة PEM (المصادقة الموحدة + المصادقة بالشهادة).
• channels.msteams.certificateThumbprint: بصمة الشهادة؛ مقبولة، لكنها غير مطلوبة للمصادقة.
• channels.msteams.useManagedIdentity: تمكين المصادقة بالهوية المُدارة (الوضع الموحد).
• channels.msteams.managedIdentityClientId: معرّف العميل للهوية المُدارة المعيّنة من المستخدم.
• channels.msteams.sharePointSiteId: معرّف موقع SharePoint لرفع الملفات في المحادثات الجماعية/القنوات (راجع إرسال الملفات في المحادثات الجماعية).
• channels.msteams.welcomeCard، channels.msteams.groupWelcomeCard، channels.msteams.promptStarters: بطاقة Adaptive Card ترحيبية تظهر عند أول تواصل عبر رسالة مباشرة/مجموعة، وأزرار المطالبات المقترحة فيها.
• channels.msteams.responsePrefix: نص يُضاف في بداية الردود الصادرة.
• channels.msteams.feedbackEnabled (الافتراضي true)، وchannels.msteams.feedbackReflection (الافتراضي true)، وchannels.msteams.feedbackReflectionCooldownMs: ملاحظات الإعجاب/عدم الإعجاب على الردود ومتابعة التأمل بشأن الملاحظات السلبية.
• channels.msteams.sso، channels.msteams.delegatedAuth: اتصال OAuth الخاص بـ Bot Framework ونطاقات Graph المفوضة للتدفقات المدعومة بتسجيل الدخول الأحادي؛ يتطلب sso.enabled: true وجود sso.connectionName.

​

التوجيه والجلسات

• تتبع مفاتيح الجلسات تنسيق الوكيل القياسي (راجع /concepts/session):
  • تتشارك الرسائل المباشرة الجلسة الرئيسية (agent:<agentId>:<mainKey>).
  • تستخدم رسائل القنوات/المجموعات معرّف المحادثة:
    • agent:<agentId>:msteams:channel:<conversationId>
    • agent:<agentId>:msteams:group:<conversationId>

​

نمط الرد: السلاسل مقابل المنشورات

• thread في قناة بنمط السلاسل ← تظهر الردود متداخلة بصورة غير ملائمة.
• top-level في قناة بنمط المنشورات ← تظهر الردود كمنشورات مستقلة من المستوى الأعلى بدلًا من ظهورها داخل السلسلة.

{
  channels: {
    msteams: {
      replyStyle: "thread",
      teams: {
        "19:abc...@thread.tacv2": {
          channels: {
            "19:xyz...@thread.tacv2": {
              replyStyle: "top-level",
            },
          },
        },
      },
    },
  },
}

​

أسبقية تحديد القيمة

1. لكل قناة - channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle
2. لكل فريق - channels.msteams.teams.<teamId>.replyStyle
3. عام - channels.msteams.replyStyle
4. القيمة الافتراضية الضمنية - مشتقة من requireMention:
   • requireMention: true ← thread
   • requireMention: false ← top-level

​

الحفاظ على سياق السلسلة

​

المرفقات والصور

• الرسائل المباشرة: تعمل الصور ومرفقات الملفات عبر واجهات ملفات روبوت Teams.
• القنوات/المجموعات: توجد المرفقات في تخزين M365 ‏(SharePoint/OneDrive). لا تتضمن حمولة Webhook سوى عنصر HTML نائب، لا بايتات الملف الفعلية. تلزم أذونات Graph API لتنزيل مرفقات القنوات.
• لعمليات الإرسال الصريحة التي يبدأ فيها الملف أولًا، استخدم action=upload-file مع media / filePath / path؛ تصبح message الاختيارية النص/التعليق المصاحب، وتتجاوز filename (أو title) الاسم المرفوع.

​

إرسال الملفات في المحادثات الجماعية

​

لماذا تحتاج المحادثات الجماعية إلى SharePoint

​

الإعداد

1. أضف أذونات Graph API في Entra ID (Azure AD) ← App Registration:
   • Sites.ReadWrite.All (Application) - رفع الملفات إلى SharePoint.
   • ChatMember.Read.All (Application) - الإذن الأقل امتيازًا على مستوى المستأجر لإرسال الملفات في المحادثات الجماعية. يعمل Chat.Read.All أيضًا، ويغطي ذلك بالفعل عند تمكين سجل المحادثات الجماعية. كبديل لكل محادثة، استخدم إذن الموافقة الخاص بالمورد ChatMember.Read.Chat.
2. امنح موافقة المسؤول للمستأجر.
3. احصل على معرّف موقع SharePoint:
   # عبر Graph Explorer أو curl باستخدام رمز مميز صالح:
   curl -H "Authorization: Bearer $TOKEN" \
     "https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-path}"
   
   # مثال: لموقع على "contoso.sharepoint.com/sites/BotFiles"
   curl -H "Authorization: Bearer $TOKEN" \
     "https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/BotFiles"
   
   # تتضمن الاستجابة: "id": "contoso.sharepoint.com,guid1,guid2"
   
4. إعداد OpenClaw:
   {
     channels: {
       msteams: {
         // ... إعدادات أخرى ...
         sharePointSiteId: "contoso.sharepoint.com,guid1,guid2",
       },
     },
   }
   

​

سلوك المشاركة

​

السلوك الاحتياطي

​

موقع تخزين الملفات

​

استطلاعات الرأي (البطاقات التكيفية)

• CLI: openclaw message poll --channel msteams --target conversation:<id> --poll-question "..." --poll-option "..." --poll-option "...".
• يسجّل Gateway الأصوات في SQLite لحالة Plugin في OpenClaw ضمن state/openclaw.sqlite.
• تُستورد ملفات msteams-polls.json الموجودة بواسطة openclaw doctor --fix، وليس بواسطة Plugin قيد التشغيل.
• يجب أن يظل Gateway متصلًا لتسجيل الأصوات.
• لا تنشر استطلاعات الرأي ملخصات النتائج تلقائيًا، ولا توجد حتى الآن CLI لنتائج الاستطلاعات.

​

بطاقات العرض

{
  action: "send",
  channel: "msteams",
  target: "user:<id>",
  presentation: {
    title: "مرحبًا",
    blocks: [{ type: "text", text: "مرحبًا!" }],
  },
}

openclaw message send --channel msteams \
  --target "conversation:19:abc...@thread.tacv2" \
  --presentation '{"title":"مرحبًا","blocks":[{"type":"text","text":"مرحبًا!"}]}'

​

تنسيقات الوجهة

# الإرسال إلى مستخدم حسب المعرّف
openclaw message send --channel msteams --target "user:40a1a0ed-..." --message "مرحبًا"

# الإرسال إلى مستخدم حسب اسم العرض (يؤدي إلى البحث عبر Graph API)
openclaw message send --channel msteams --target "user:John Smith" --message "مرحبًا"

# الإرسال إلى دردشة جماعية أو قناة
openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" --message "مرحبًا"

# إرسال بطاقة عرض إلى محادثة
openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" \
  --presentation '{"title":"مرحبًا","blocks":[{"type":"text","text":"مرحبًا"}]}'

{
  action: "send",
  channel: "msteams",
  target: "user:John Smith",
  message: "مرحبًا!",
}

{
  action: "send",
  channel: "msteams",
  target: "conversation:19:abc...@thread.tacv2",
  presentation: {
    title: "مرحبًا",
    blocks: [{ type: "text", text: "مرحبًا" }],
  },
}

​

المراسلة الاستباقية

• لا يمكن إرسال الرسائل الاستباقية إلا بعد تفاعل المستخدم، لأن OpenClaw يخزّن مراجع المحادثة عندئذٍ.
• راجع /gateway/configuration لمعرفة dmPolicy وآلية التقييد بقائمة السماح.

​

معرّفات الفريق والقناة (خطأ شائع)

https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?groupId=...
                                    └────────────────────────────┘
                                    معرّف محادثة الفريق (فك ترميز URL لهذا المعرّف)

https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?groupId=...
                                      └─────────────────────────┘
                                      معرّف القناة (فك ترميز URL لهذا المعرّف)

• مفتاح الفريق = مقطع المسار بعد /team/ (بعد فك ترميز URL، مثل 19:Bk4j...@thread.tacv2؛ وقد تعرض المستأجرات الأقدم @thread.skype، وهو صالح أيضًا).
• مفتاح القناة = مقطع المسار بعد /channel/ (بعد فك ترميز URL).
• تجاهل معلمة الاستعلام groupId في توجيه OpenClaw. فهي معرّف مجموعة Microsoft Entra، وليست معرّف محادثة Bot Framework المستخدم في أنشطة Teams الواردة.

​

القنوات الخاصة

1. استخدم القنوات القياسية للتفاعل مع البوت.
2. استخدم الرسائل المباشرة؛ يمكن للمستخدمين دائمًا مراسلة البوت مباشرةً.
3. استخدم Graph API للوصول إلى السجل (يتطلب ChannelMessage.Read.All).

​

استكشاف الأخطاء وإصلاحها

​

المشكلات الشائعة

• الصور لا تظهر في القنوات: أذونات Graph أو موافقة المسؤول مفقودة. أعد تثبيت تطبيق Teams، ثم أغلق Teams بالكامل وأعد فتحه.
• لا توجد استجابات في القناة: الإشارات مطلوبة افتراضيًا؛ عيّن channels.msteams.requireMention=false أو أجرِ الإعداد لكل فريق/قناة.
• عدم تطابق الإصدار (لا يزال Teams يعرض البيان القديم): أزل التطبيق ثم أضفه مجددًا، وأغلق Teams بالكامل لتحديثه.
• استجابة 401 Unauthorized من Webhook: هذا متوقع عند الاختبار يدويًا من دون Azure JWT؛ ويعني أن نقطة النهاية متاحة لكن المصادقة فشلت. استخدم Azure Web Chat لإجراء الاختبار بصورة صحيحة.

​

أخطاء رفع البيان

• “Icon file cannot be empty”: يشير البيان إلى ملفات أيقونات حجمها 0 بايت. أنشئ أيقونات PNG صالحة (32x32 لـ outline.png، و192x192 لـ color.png).
• “webApplicationInfo.Id already in use”: لا يزال التطبيق مثبتًا في فريق/دردشة أخرى. ابحث عنه وألغِ تثبيته أولًا، أو انتظر 5-10 دقائق حتى ينتشر التغيير.
• ظهور “Something went wrong” عند الرفع: ارفع عبر https://admin.teams.microsoft.com بدلًا من ذلك، وافتح أدوات المطور في المتصفح (F12) ← علامة التبويب Network، ثم افحص نص الاستجابة لمعرفة الخطأ الفعلي.
• فشل التحميل الجانبي: جرّب “Upload an app to your org’s app catalog” بدلًا من “Upload a custom app”؛ فهذا يتجاوز غالبًا قيود التحميل الجانبي.

​

أذونات RSC لا تعمل

1. تحقق من تطابق webApplicationInfo.id تمامًا مع App ID الخاص بالبوت.
2. أعد رفع التطبيق وثبّته مجددًا في الفريق/الدردشة.
3. تحقق مما إذا كان مسؤول المؤسسة قد حظر أذونات RSC.
4. تأكد من استخدام النطاق الصحيح: ChannelMessage.Read.Group للفرق، وChatMessage.Read.Chat للدردشات الجماعية.

​

المراجع

• إنشاء Azure Bot - دليل إعداد Azure Bot
• بوابة مطوري Teams - إنشاء تطبيقات Teams وإدارتها
• مخطط بيان تطبيق Teams
• تلقي رسائل القناة باستخدام RSC
• مرجع أذونات RSC
• معالجة ملفات بوت Teams (تتطلب القناة/المجموعة Graph)
• المراسلة الاستباقية
• @microsoft/teams.cli - CLI لـ Teams لإدارة البوتات

​

ذو صلة

• نظرة عامة على القنوات - جميع القنوات المدعومة
• الاقتران - مصادقة الرسائل المباشرة وتدفق الاقتران
• المجموعات - سلوك الدردشة الجماعية وتقييد الإشارات
• توجيه القنوات - توجيه جلسات الرسائل
• الأمان - نموذج الوصول والتقوية