Microsoft Teams

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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   # verify you're logged in and see your tenant info

# One-time setup (persistent URL across sessions):
devtunnel create my-openclaw-bot --allow-anonymous
devtunnel port create my-openclaw-bot -p 3978 --protocol auto

# Each dev session:
devtunnel host my-openclaw-bot
# Your endpoint: https://<tunnel-id>.devtunnels.ms/api/messages

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

• ينشئ تطبيق Entra ID (Azure AD)
• يولّد سر عميل
• يبني ويرفع بيان تطبيق Teams (مع الأيقونات)
• يسجل البوت (مُدار بواسطة Teams افتراضيًا - لا حاجة إلى اشتراك Azure)

{
  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.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 },
          },
        },
      },
    },
  },
}

​

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

أُضيفت في 2026.4.11

​

الخيار A: المصادقة المعتمدة على الشهادة

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

​

الخيار B: Azure Managed Identity

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

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

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

{
  channels: {
    msteams: {
      enabled: true,
      appId: "<APP_ID>",
      tenantId: "<TENANT_ID>",
      authType: "federated",
      useManagedIdentity: true,
      managedIdentityClientId: "<MI_CLIENT_ID>",
      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.

​

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

​

التطوير المحلي (الأنفاق)

# One-time setup:
devtunnel create my-openclaw-bot --allow-anonymous
devtunnel port create my-openclaw-bot -p 3978 --protocol auto

# Each dev session:
devtunnel host my-openclaw-bot

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

​

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

teams app doctor <teamsAppId>

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

​

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

• MSTEAMS_APP_ID
• MSTEAMS_APP_PASSWORD
• MSTEAMS_TENANT_ID
• MSTEAMS_AUTH_TYPE (اختياري: "secret" أو "federated")
• MSTEAMS_CERTIFICATE_PATH (موحّد + شهادة)
• MSTEAMS_CERTIFICATE_THUMBPRINT (اختياري، غير مطلوب للمصادقة)
• MSTEAMS_USE_MANAGED_IDENTITY (موحّد + هوية مُدارة)
• MSTEAMS_MANAGED_IDENTITY_CLIENT_ID (MI معيّنة من المستخدم فقط)

​

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

• إذن RSC باسم Member.Read.Group (موجود مسبقًا في البيان الموصى به)
• لعمليات البحث عبر الفرق: إذن تطبيق Graph باسم User.Read.All مع موافقة المسؤول

​

سياق السجل

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

​

أذونات RSC الحالية في 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

​

مثال على بيان 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 أذونات قراءة/إرسال القناة إذا كنت تريد حركة مرور القناة.

​

تحديث تطبيق موجود

# Download, edit, and re-upload the manifest
teams app manifest download <teamsAppId> manifest.json
# Edit manifest.json locally...
teams app manifest upload manifest.json <teamsAppId>
# Version is auto-bumped if content changed

​

القدرات: RSC فقط مقابل Graph

​

مع Teams RSC فقط (التطبيق مثبت، ولا توجد أذونات Graph API)

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

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

​

مع Teams RSC + أذونات تطبيق Microsoft Graph

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

​

RSC مقابل Graph API

​

الوسائط والسجل المفعّلان عبر Graph (مطلوب للقنوات)

1. في تسجيل التطبيق في Entra ID (Azure AD)، أضف أذونات تطبيق Microsoft Graph:
   • ChannelMessage.Read.All (مرفقات القناة + السجل)
   • Chat.Read.All أو ChatMessage.Read.All (دردشات المجموعة)
2. امنح موافقة المسؤول للمستأجر.
3. ارفع إصدار بيان تطبيق Teams، وأعد تحميله، وأعد تثبيت التطبيق في Teams.
4. اخرج من Teams بالكامل ثم شغّله من جديد لمسح بيانات تعريف التطبيق المخزنة مؤقتًا.

​

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

​

مهلات Webhook

• مهلات Gateway
• Teams يعيد محاولة إرسال الرسالة (ما يسبب تكرارات)
• ردودًا مسقطة

​

التنسيق

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

​

الإعداد

• channels.msteams.enabled: تمكين/تعطيل القناة.
• channels.msteams.appId، channels.msteams.appPassword، channels.msteams.tenantId: بيانات اعتماد البوت.
• 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: حجم أجزاء النص الصادر.
• channels.msteams.chunkMode: length (الافتراضي) أو newline للتقسيم عند الأسطر الفارغة (حدود الفقرات) قبل التقسيم حسب الطول.
• channels.msteams.mediaAllowHosts: قائمة سماح لمضيفي المرفقات الواردة (الافتراضي نطاقات Microsoft/Teams).
• channels.msteams.mediaAuthAllowHosts: قائمة سماح لإرفاق ترويسات Authorization عند إعادة محاولة الوسائط (الافتراضي مضيفو Graph + Bot Framework).
• channels.msteams.requireMention: طلب @mention في القنوات/المجموعات (الافتراضي 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.actions.memberInfo: تمكين أو تعطيل إجراء معلومات العضو المدعوم من Graph (الافتراضي: ممكّن عندما تكون بيانات اعتماد Graph متاحة).
• channels.msteams.authType: نوع المصادقة - "secret" (الافتراضي) أو "federated".
• channels.msteams.certificatePath: المسار إلى ملف شهادة PEM (مصادقة federated + الشهادة).
• channels.msteams.certificateThumbprint: بصمة الشهادة (اختيارية، غير مطلوبة للمصادقة).
• channels.msteams.useManagedIdentity: تمكين مصادقة الهوية المدارة (وضع federated).
• channels.msteams.managedIdentityClientId: معرف العميل للهوية المدارة المعينة من المستخدم.
• channels.msteams.sharePointSiteId: معرف موقع SharePoint لرفع الملفات في محادثات/قنوات المجموعات (راجع إرسال الملفات في محادثات المجموعات).

​

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

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

​

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

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

{
  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

​

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

​

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

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

​

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

​

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

​

الإعداد

1. أضف أذونات Graph API في Entra ID (Azure AD) → تسجيل التطبيق:
   • Sites.ReadWrite.All (Application) - رفع الملفات إلى SharePoint
   • Chat.Read.All (Application) - اختياري، يتيح روابط مشاركة لكل مستخدم
2. امنح موافقة المسؤول للمستأجر.
3. احصل على معرف موقع SharePoint الخاص بك:
   # Via Graph Explorer or curl with a valid token:
   curl -H "Authorization: Bearer $TOKEN" \
     "https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-path}"
   
   # Example: for a site at "contoso.sharepoint.com/sites/BotFiles"
   curl -H "Authorization: Bearer $TOKEN" \
     "https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/BotFiles"
   
   # Response includes: "id": "contoso.sharepoint.com,guid1,guid2"
   
4. اضبط OpenClaw:
   {
     channels: {
       msteams: {
         // ... other config ...
         sharePointSiteId: "contoso.sharepoint.com,guid1,guid2",
       },
     },
   }
   

​

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

​

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

​

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

​

الاستطلاعات (Adaptive Cards)

• CLI: openclaw message poll --channel msteams --target conversation:<id> ...
• يسجل Gateway الأصوات في ~/.openclaw/msteams-polls.json.
• يجب أن يبقى Gateway متصلاً بالإنترنت لتسجيل الأصوات.
• لا تنشر الاستطلاعات ملخصات النتائج تلقائياً بعد (افحص ملف التخزين إذا لزم الأمر).

​

بطاقات العرض التقديمي

{
  action: "send",
  channel: "msteams",
  target: "user:<id>",
  presentation: {
    title: "Hello",
    blocks: [{ type: "text", text: "Hello!" }],
  },
}

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

​

تنسيقات الهدف

# Send to a user by ID
openclaw message send --channel msteams --target "user:40a1a0ed-..." --message "Hello"

# Send to a user by display name (triggers Graph API lookup)
openclaw message send --channel msteams --target "user:John Smith" --message "Hello"

# Send to a group chat or channel
openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" --message "Hello"

# Send a presentation card to a conversation
openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" \
  --presentation '{"title":"Hello","blocks":[{"type":"text","text":"Hello"}]}'

{
  action: "send",
  channel: "msteams",
  target: "user:John Smith",
  message: "Hello!",
}

{
  action: "send",
  channel: "msteams",
  target: "conversation:19:abc...@thread.tacv2",
  presentation: {
    title: "Hello",
    blocks: [{ type: "text", text: "Hello" }],
  },
}

​

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

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

​

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

https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?groupId=...
                                    └────────────────────────────┘
                                    Team conversation ID (URL-decode this)

https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?groupId=...
                                      └─────────────────────────┘
                                      Channel ID (URL-decode this)

• مفتاح الفريق = مقطع المسار بعد /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 بدلاً من ذلك، وافتح DevTools في المتصفح (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 - Teams CLI لإدارة البوت

​

ذات صلة

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