​

Microsoft Teams (plugin)

“Laat alle hoop varen, gij die hier binnentreedt.”

​

Plugin vereist

openclaw plugins install @openclaw/msteams

openclaw plugins install ./extensions/msteams

​

Snelle installatie (beginner)

1. Installeer de Microsoft Teams-plugin.
2. Maak een Azure Bot aan (App ID + client secret + tenant ID).
3. Configureer OpenClaw met deze referenties.
4. Stel /api/messages bloot (standaard poort 3978) via een publieke URL of tunnel.
5. Installeer het Teams-app-pakket en start de Gateway.

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

​

Doelen

• Met OpenClaw praten via Teams DM’s, groepschats of kanalen.
• Routering deterministisch houden: antwoorden gaan altijd terug naar het kanaal waar ze zijn ontvangen.
• Standaard veilig kanaalgedrag (mentions vereist tenzij anders geconfigureerd).

​

Config-wegschrijvingen

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

​

Toegangsbeheer (DM’s + groepen)

• Standaard: channels.msteams.dmPolicy = "pairing". Onbekende afzenders worden genegeerd tot goedkeuring.
• channels.msteams.allowFrom accepteert AAD-object-ID’s, UPN’s of weergavenamen. De wizard zet namen om naar ID’s via Microsoft Graph wanneer de referenties dat toestaan.

• Standaard: channels.msteams.groupPolicy = "allowlist" (geblokkeerd tenzij je groupAllowFrom toevoegt). Gebruik channels.defaults.groupPolicy om de standaard te overschrijven wanneer niet ingesteld.
• channels.msteams.groupAllowFrom bepaalt welke afzenders groepschats/kanalen kunnen triggeren (valt terug op channels.msteams.allowFrom).
• Stel groupPolicy: "open" in om elk lid toe te staan (standaard nog steeds mention‑vereist).
• Om geen kanalen toe te staan, stel channels.msteams.groupPolicy: "disabled" in.

{
  channels: {
    msteams: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["[email protected]"],
    },
  },
}

• Beperk groeps-/kanaalantwoorden door teams en kanalen te vermelden onder channels.msteams.teams.
• Sleutels kunnen team-ID’s of namen zijn; kanaalsleutels kunnen conversatie-ID’s of namen zijn.
• Wanneer groupPolicy="allowlist" en een teams‑toegestane lijst aanwezig is, worden alleen vermelde teams/kanalen geaccepteerd (mention‑vereist).
• De configuratiewizard accepteert Team/Channel‑items en slaat ze voor je op.
• Bij opstarten zet OpenClaw team-/kanaal- en gebruikersnamen in de toegestane lijst om naar ID’s (wanneer Graph-rechten dit toestaan) en logt de mapping; niet-opgeloste items blijven zoals ingevoerd.

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

​

Hoe het werkt

1. Installeer de Microsoft Teams-plugin.
2. Maak een Azure Bot aan (App ID + secret + tenant ID).
3. Bouw een Teams-app-pakket dat naar de bot verwijst en de onderstaande RSC-rechten bevat.
4. Upload/installeer de Teams-app in een team (of persoonlijke scope voor DM’s).
5. Configureer msteams in ~/.openclaw/openclaw.json (of omgevingsvariabelen) en start de Gateway.
6. De Gateway luistert standaard naar Bot Framework-webhookverkeer op /api/messages.

​

Azure Bot-installatie (Vereisten)

​

Stap 1: Azure Bot maken

1. Ga naar Create Azure Bot
2. Vul het tabblad Basics in:

   Waarde	Waarde
   Bot-naam	Je botnaam, bijv. openclaw-msteams (moet uniek zijn)
   Abonnement	Selecteer je Azure-abonnement
   Resourcegroep	Nieuw aanmaken of bestaand gebruiken
   Prijscategorie	Free voor dev/test
   Type app	Single Tenant (aanbevolen – zie opmerking hieronder)
   Type aanmaak	Nieuwe Microsoft App-ID maken

Deprecatiebericht: Het aanmaken van nieuwe multi-tenant bots is na 2025-07-31 afgeschaft. Gebruik Single Tenant voor nieuwe bots.

3. Klik Review + create → Create (wacht ~1–2 minuten)

​

Stap 2: Referenties ophalen

1. Ga naar je Azure Bot-resource → Configuration
2. Kopieer Microsoft App ID → dit is je appId
3. Klik Manage Password → ga naar de App-registratie
4. Onder Certificates & secrets → New client secret → kopieer de Value → dit is je appPassword
5. Ga naar Overview → kopieer Directory (tenant) ID → dit is je tenantId

​

Stap 3: Messaging-endpoint configureren

1. In Azure Bot → Configuration
2. Stel Messaging endpoint in op je webhook-URL:
   • Productie: https://your-domain.com/api/messages
   • Lokale dev: gebruik een tunnel (zie Lokale ontwikkeling hieronder)

​

Stap 4: Teams-kanaal inschakelen

1. In Azure Bot → Channels
2. Klik Microsoft Teams → Configure → Save
3. Accepteer de Servicevoorwaarden

​

Lokale ontwikkeling (Tunneling)

ngrok http 3978
# Copy the https URL, e.g., https://abc123.ngrok.io
# Set messaging endpoint to: https://abc123.ngrok.io/api/messages

tailscale funnel 3978
# Use your Tailscale funnel URL as the messaging endpoint

​

Teams Developer Portal (Alternatief)

1. Klik + New app
2. Vul basisinfo in (naam, beschrijving, ontwikkelaarsinfo)
3. Ga naar App features → Bot
4. Selecteer Enter a bot ID manually en plak je Azure Bot App ID
5. Vink scopes aan: Personal, Team, Group Chat
6. Klik Distribute → Download app package
7. In Teams: Apps → Manage your apps → Upload a custom app → selecteer de ZIP

​

De bot testen

1. In Azure Portal → je Azure Bot-resource → Test in Web Chat
2. Stuur een bericht – je zou een antwoord moeten zien
3. Dit bevestigt dat je webhook-endpoint werkt vóór Teams-installatie

1. Installeer de Teams-app (sideload of org-catalogus)
2. Zoek de bot in Teams en stuur een DM
3. Controleer Gateway-logs op inkomende activiteit

​

Installatie (minimaal, alleen tekst)

1. Installeer de Microsoft Teams-plugin
   • Via npm: openclaw plugins install @openclaw/msteams
   • Via een lokale checkout: openclaw plugins install ./extensions/msteams
2. Bot-registratie
   • Maak een Azure Bot aan (zie hierboven) en noteer:
     • App ID
     • Client secret (App-wachtwoord)
     • Tenant ID (single-tenant)
3. Teams-app-manifest
   • Voeg een bot‑item toe met botId = <App ID>.
   • Scopes: personal, team, groupChat.
   • supportsFiles: true (vereist voor bestandsverwerking in persoonlijke scope).
   • Voeg RSC-rechten toe (hieronder).
   • Maak iconen: outline.png (32x32) en color.png (192x192).
   • Zip alle drie bestanden samen: manifest.json, outline.png, color.png.
4. OpenClaw configureren
   {
     "msteams": {
       "enabled": true,
       "appId": "<APP_ID>",
       "appPassword": "<APP_PASSWORD>",
       "tenantId": "<TENANT_ID>",
       "webhook": { "port": 3978, "path": "/api/messages" }
     }
   }
   
   Je kunt ook omgevingsvariabelen gebruiken in plaats van config-sleutels:
   • MSTEAMS_APP_ID
   • MSTEAMS_APP_PASSWORD
   • MSTEAMS_TENANT_ID
5. Bot-endpoint
   • Stel het Azure Bot Messaging Endpoint in op:
     • https://<host>:3978/api/messages (of je gekozen pad/poort).
6. Gateway starten
   • Het Teams-kanaal start automatisch wanneer de plugin is geïnstalleerd en msteams‑config met referenties bestaat.

​

Contextgeschiedenis

• channels.msteams.historyLimit bepaalt hoeveel recente kanaal-/groepsberichten in de prompt worden opgenomen.
• Valt terug op messages.groupChat.historyLimit. Stel 0 in om uit te schakelen (standaard 50).
• DM-geschiedenis kan worden beperkt met channels.msteams.dmHistoryLimit (gebruikersbeurten). Per‑gebruiker‑overschrijvingen: channels.msteams.dms["<user_id>"].historyLimit.

​

Huidige Teams RSC-rechten (Manifest)

• ChannelMessage.Read.Group (Application) – alle kanaalberichten ontvangen zonder @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) – alle groepschatberichten ontvangen zonder @mention

​

Voorbeeld Teams-manifest (geredigeerd)

{
  "$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" }
      ]
    }
  }
}

​

Manifest‑kanttekeningen (verplichte velden)

• bots[].botId moet overeenkomen met de Azure Bot App ID.
• webApplicationInfo.id moet overeenkomen met de Azure Bot App ID.
• bots[].scopes moet de oppervlakken bevatten die je wilt gebruiken (personal, team, groupChat).
• bots[].supportsFiles: true is vereist voor bestandsverwerking in persoonlijke scope.
• authorization.permissions.resourceSpecific moet kanaal lezen/verzenden bevatten als je kanaalverkeer wilt.

​

Een bestaande app bijwerken

1. Werk je manifest.json bij met de nieuwe instellingen
2. Verhoog het veld version (bijv. 1.0.0 → 1.1.0)
3. Zip opnieuw het manifest met iconen (manifest.json, outline.png, color.png)
4. Upload de nieuwe zip:
   • Optie A (Teams Admin Center): Teams Admin Center → Teams apps → Manage apps → zoek je app → Upload new version
   • Optie B (Sideload): In Teams → Apps → Manage your apps → Upload a custom app
5. Voor teamkanalen: herinstalleer de app in elk team zodat nieuwe rechten ingaan
6. Teams volledig afsluiten en opnieuw starten (niet alleen het venster sluiten) om gecachte app‑metadata te wissen

​

Mogelijkheden: alleen RSC vs Graph

​

Met alleen Teams RSC (app geïnstalleerd, geen Graph API-rechten)

• Kanaalbericht tekst lezen.
• Kanaalbericht tekst verzenden.
• Persoonlijke (DM) bestandsbijlagen ontvangen.

• Afbeeldings- of bestandsinhoud in kanalen/groepen (payload bevat alleen HTML‑stub).
• Bijlagen downloaden die in SharePoint/OneDrive zijn opgeslagen.
• Berichtgeschiedenis lezen (buiten de live webhook‑event).

​

Met Teams RSC + Microsoft Graph Application-rechten

• Gehoste inhoud downloaden (afbeeldingen die in berichten zijn geplakt).
• Bestandsbijlagen downloaden die in SharePoint/OneDrive zijn opgeslagen.
• Kanaal-/chatberichtgeschiedenis lezen via Graph.

​

RSC vs Graph API

​

Graph‑ingeschakelde media + geschiedenis (vereist voor kanalen)

1. In Entra ID (Azure AD) App Registration, voeg Microsoft Graph Application permissions toe:
   • ChannelMessage.Read.All (kanaalbijlagen + geschiedenis)
   • Chat.Read.All of ChatMessage.Read.All (groepschats)
2. Verleen admin‑toestemming voor de tenant.
3. Verhoog de Teams-app manifestversie, upload opnieuw en herinstalleer de app in Teams.
4. Teams volledig afsluiten en opnieuw starten om gecachte app‑metadata te wissen.

​

Bekende beperkingen

​

Webhook‑timeouts

• Gateway‑timeouts
• Teams die het bericht opnieuw probeert te verzenden (duplicaten)
• Verloren antwoorden

​

Opmaak

• Basisopmaak werkt: vet, cursief, code, links
• Complexe markdown (tabellen, geneste lijsten) rendert mogelijk niet correct
• Adaptive Cards worden ondersteund voor polls en het verzenden van kaarten (zie hieronder)

​

Configuratie

• channels.msteams.enabled: kanaal in-/uitschakelen.
• channels.msteams.appId, channels.msteams.appPassword, channels.msteams.tenantId: bot‑referenties.
• channels.msteams.webhook.port (standaard 3978)
• channels.msteams.webhook.path (standaard /api/messages)
• channels.msteams.dmPolicy: pairing | allowlist | open | disabled (standaard: pairing)
• channels.msteams.allowFrom: toegestane lijst voor DM’s (AAD‑object‑ID’s, UPN’s of weergavenamen). De wizard zet namen om naar ID’s tijdens installatie wanneer Graph‑toegang beschikbaar is.
• channels.msteams.textChunkLimit: uitgaande tekst‑chunkgrootte.
• channels.msteams.chunkMode: length (standaard) of newline om op lege regels (alinea‑grenzen) te splitsen vóór lengte‑chunking.
• channels.msteams.mediaAllowHosts: toegestane lijst voor inkomende bijlagehosts (standaard Microsoft/Teams‑domeinen).
• channels.msteams.mediaAuthAllowHosts: toegestane lijst voor het toevoegen van Authorization‑headers bij media‑retries (standaard Graph + Bot Framework‑hosts).
• channels.msteams.requireMention: @mention vereisen in kanalen/groepen (standaard true).
• channels.msteams.replyStyle: thread | top-level (zie Antwoordstijl).
• channels.msteams.teams.<teamId>.replyStyle: per‑team overschrijving.
• channels.msteams.teams.<teamId>.requireMention: per‑team overschrijving.
• channels.msteams.teams.<teamId>.tools: standaard per‑team tool‑beleid‑overschrijvingen (allow/deny/alsoAllow) gebruikt wanneer een kanaaloverschrijving ontbreekt.
• channels.msteams.teams.<teamId>.toolsBySender: standaard per‑team per‑afzender tool‑beleid‑overschrijvingen ("*" wildcard ondersteund).
• channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle: per‑kanaal overschrijving.
• channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention: per‑kanaal overschrijving.
• channels.msteams.teams.<teamId>.channels.<conversationId>.tools: per‑kanaal tool‑beleid‑overschrijvingen (allow/deny/alsoAllow).
• channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender: per‑kanaal per‑afzender tool‑beleid‑overschrijvingen ("*" wildcard ondersteund).
• channels.msteams.sharePointSiteId: SharePoint‑site‑ID voor bestandsuploads in groepschats/kanalen (zie Bestanden verzenden in groepschats).

​

Routering & sessies

• Sessiesleutels volgen het standaard agent‑formaat (zie /concepts/session):
  • Directe berichten delen de hoofdsessie (agent:<agentId>:<mainKey>).
  • Kanaal-/groepsberichten gebruiken conversatie‑ID:
    • agent:<agentId>:msteams:channel:<conversationId>
    • agent:<agentId>:msteams:group:<conversationId>

​

Antwoordstijl: Threads vs Posts

• thread in een Threads‑kanaal → antwoorden verschijnen onhandig genest
• top-level in een Posts‑kanaal → antwoorden verschijnen als losse top‑level posts i.p.v. in de thread

{
  "msteams": {
    "replyStyle": "thread",
    "teams": {
      "19:[email protected]": {
        "channels": {
          "19:[email protected]": {
            "replyStyle": "top-level"
          }
        }
      }
    }
  }
}

​

Bijlagen & afbeeldingen

• DM’s: Afbeeldingen en bestandsbijlagen werken via Teams bot file‑API’s.
• Kanalen/groepen: Bijlagen staan in M365‑opslag (SharePoint/OneDrive). De webhook‑payload bevat alleen een HTML‑stub, niet de daadwerkelijke bytes. Graph API‑rechten zijn vereist om kanaalbijlagen te downloaden.

​

Bestanden verzenden in groepschats

​

Waarom groepschats SharePoint nodig hebben

​

Installatie

1. Voeg Graph API‑rechten toe in Entra ID (Azure AD) → App Registration:
   • Sites.ReadWrite.All (Application) – bestanden uploaden naar SharePoint
   • Chat.Read.All (Application) – optioneel, maakt per‑gebruiker deel‑links mogelijk
2. Verleen admin‑toestemming voor de tenant.
3. Haal je SharePoint‑site‑ID op:
   # 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. Configureer OpenClaw:
   {
     channels: {
       msteams: {
         // ... other config ...
         sharePointSiteId: "contoso.sharepoint.com,guid1,guid2",
       },
     },
   }
   

​

Delen gedrag

​

Fallback‑gedrag

​

Opslaglocatie van bestanden

​

Polls (Adaptive Cards)

• CLI: openclaw message poll --channel msteams --target conversation:<id> ...
• Stemmen worden door de Gateway vastgelegd in ~/.openclaw/msteams-polls.json.
• De Gateway moet online blijven om stemmen te registreren.
• Polls plaatsen nog geen automatische resultaat‑samenvattingen (inspecteer indien nodig het opslagbestand).

​

Adaptive Cards (vrij)

{
  "action": "send",
  "channel": "msteams",
  "target": "user:<id>",
  "card": {
    "type": "AdaptiveCard",
    "version": "1.5",
    "body": [{ "type": "TextBlock", "text": "Hello!" }]
  }
}

openclaw message send --channel msteams \
  --target "conversation:19:[email protected]" \
  --card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello!"}]}'

​

Target formats

# 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:[email protected]" --message "Hello"

# Send an Adaptive Card to a conversation
openclaw message send --channel msteams --target "conversation:19:[email protected]" \
  --card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Hello"}]}'

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

{
  "action": "send",
  "channel": "msteams",
  "target": "conversation:19:[email protected]",
  "card": {
    "type": "AdaptiveCard",
    "version": "1.5",
    "body": [{ "type": "TextBlock", "text": "Hello" }]
  }
}

​

Proactieve berichten

• Proactieve berichten zijn alleen mogelijk nadat een gebruiker heeft geïnteracteerd, omdat we dan conversatie‑referenties opslaan.
• Zie /gateway/configuration voor dmPolicy en gating via toegestane lijsten.

​

Team- en kanaal‑ID’s (veelgemaakte valkuil)

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

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

• Team‑ID = padsegment na /team/ (URL‑gedecodeerd, bijv. 19:[email protected])
• Kanaal‑ID = padsegment na /channel/ (URL‑gedecodeerd)
• Negeer de queryparameter groupId

​

Privékanalen

1. Gebruik standaardkanalen voor bot‑interacties
2. Gebruik DM’s – gebruikers kunnen de bot altijd direct berichten
3. Gebruik Graph API voor historische toegang (vereist ChannelMessage.Read.All)

​

Veelvoorkomende problemen

​

Problemen oplossen

• Afbeeldingen verschijnen niet in kanalen: Graph‑rechten of admin‑toestemming ontbreken. Herinstalleer de Teams‑app en sluit/open Teams volledig.
• Geen antwoorden in kanaal: mentions zijn standaard vereist; stel channels.msteams.requireMention=false in of configureer per team/kanaal.
• Versiemismatch (Teams toont oud manifest): verwijder en voeg de app opnieuw toe en sluit Teams volledig.
• 401 Unauthorized van webhook: Verwacht bij handmatig testen zonder Azure JWT – betekent dat het endpoint bereikbaar is maar authenticatie faalt. Gebruik Azure Web Chat om correct te testen.

​

Manifest‑uploadfouten

• “Icon file cannot be empty”: Het manifest verwijst naar iconen van 0 bytes. Maak geldige PNG‑iconen (32x32 voor outline.png, 192x192 voor color.png).
• “webApplicationInfo.Id already in use”: De app is nog geïnstalleerd in een ander team/chat. Verwijder die eerst of wacht 5–10 minuten op propagatie.
• “Something went wrong” bij upload: Upload via https://admin.teams.microsoft.com, open DevTools (F12) → Network‑tab en controleer de response‑body voor de echte fout.
• Sideload mislukt: Probeer “Upload an app to your org’s app catalog” i.p.v. “Upload a custom app” – dit omzeilt vaak sideload‑beperkingen.

​

RSC‑rechten werken niet

1. Controleer of webApplicationInfo.id exact overeenkomt met de App ID van je bot
2. Upload de app opnieuw en herinstalleer in het team/de chat
3. Controleer of je org‑admin RSC‑rechten heeft geblokkeerd
4. Bevestig dat je de juiste scope gebruikt: ChannelMessage.Read.Group voor teams, ChatMessage.Read.Chat voor groepschats

​

Referenties

• Create Azure Bot – Azure Bot‑installatiehandleiding
• Teams Developer Portal – Teams‑apps maken/beheren
• Teams app manifest schema
• Receive channel messages with RSC
• RSC permissions reference
• Teams bot file handling (kanaal/groep vereist Graph)
• Proactive messaging