Microsoft Teams

Status: tekst + DM-bijlagen worden ondersteund; bestanden verzenden naar kanalen/groepen vereist sharePointSiteId + Graph-machtigingen (zie Bestanden verzenden in groepschats). Polls worden verzonden via Adaptive Cards. Berichtacties bieden expliciet upload-file voor verzendingen waarbij het bestand eerst komt.

Gebundelde Plugin

Microsoft Teams wordt in huidige OpenClaw-releases meegeleverd als gebundelde Plugin, dus in de normale packaged build is geen aparte installatie vereist.

Als je een oudere build gebruikt of een aangepaste installatie die gebundelde Teams uitsluit, installeer dan het npm-pakket rechtstreeks:

openclaw plugins install @openclaw/msteams

Gebruik het bare pakket om de huidige officiële release-tag te volgen. Pin alleen een exacte versie wanneer je een reproduceerbare installatie nodig hebt.

Lokale checkout (wanneer je vanuit een git-repo draait):

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

Details: Plugins

Snelle configuratie

De @microsoft/teams.cli handelt botregistratie, manifestcreatie en credentialgeneratie af met één opdracht.

1. Installeer en log in

npm install -g @microsoft/teams.cli@previewteams loginteams status   # verify you're logged in and see your tenant info

2. Start een tunnel (Teams kan localhost niet bereiken)

Installeer en authenticeer de devtunnel CLI als je dat nog niet hebt gedaan (aan-de-slaggids).

# One-time setup (persistent URL across sessions):devtunnel create my-openclaw-bot --allow-anonymousdevtunnel 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

Alternatieven: ngrok http 3978 of tailscale funnel 3978 (maar deze kunnen per sessie van URL veranderen).

3. Maak de app

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

Deze ene opdracht:

• Maakt een Entra ID-toepassing (Azure AD) aan
• Genereert een clientsecret
• Bouwt en uploadt een Teams-appmanifest (met iconen)
• Registreert de bot (standaard beheerd door Teams - geen Azure-abonnement nodig)

De output toont CLIENT_ID, CLIENT_SECRET, TENANT_ID en een Teams App ID - noteer deze voor de volgende stappen. De opdracht biedt ook aan om de app rechtstreeks in Teams te installeren.

4. Configureer OpenClaw met de credentials uit de output:

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

Of gebruik omgevingsvariabelen rechtstreeks: MSTEAMS_APP_ID, MSTEAMS_APP_PASSWORD, MSTEAMS_TENANT_ID.

5. Installeer de app in Teams

teams app create vraagt je om de app te installeren - selecteer "Install in Teams". Als je dit hebt overgeslagen, kun je de link later ophalen:

teams app get <teamsAppId> --install-link

6. Controleer of alles werkt

teams app doctor <teamsAppId>

Dit voert diagnostiek uit voor botregistratie, AAD-appconfiguratie, manifestgeldigheid en SSO-configuratie.

Overweeg voor productie-implementaties om gefedereerde authenticatie (certificaat of managed identity) te gebruiken in plaats van clientsecrets.

Doelen

• Praat met OpenClaw via Teams-DM's, groepschats of kanalen.
• Houd routing deterministisch: antwoorden gaan altijd terug naar het kanaal waarop ze zijn binnengekomen.
• Gebruik standaard veilig kanaalgedrag (vermeldingen vereist tenzij anders geconfigureerd).

Configuratieschrijfacties

Standaard mag Microsoft Teams configuratie-updates schrijven die worden getriggerd door /config set|unset (vereist commands.config: true).

Schakel uit met:

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

Toegangscontrole (DM's + groepen)

DM-toegang

• Standaard: channels.msteams.dmPolicy = "pairing". Onbekende afzenders worden genegeerd totdat ze zijn goedgekeurd.
• channels.msteams.allowFrom moet stabiele AAD-object-ID's of statische toegangsgroepen voor afzenders gebruiken, zoals accessGroup:core-team.
• Vertrouw niet op UPN-/weergavenaam-matching voor allowlists - die kunnen veranderen. OpenClaw schakelt directe naammatching standaard uit; schakel expliciet in met channels.msteams.dangerouslyAllowNameMatching: true.
• De wizard kan namen omzetten naar ID's via Microsoft Graph wanneer credentials dit toestaan.

Groepstoegang

• Standaard: channels.msteams.groupPolicy = "allowlist" (geblokkeerd tenzij je groupAllowFrom toevoegt). Gebruik channels.defaults.groupPolicy om de standaardwaarde te overschrijven wanneer die niet is ingesteld.
• channels.msteams.groupAllowFrom bepaalt welke afzenders of statische toegangsgroepen voor afzenders kunnen triggeren in groepschats/kanalen (valt terug op channels.msteams.allowFrom).
• Stel groupPolicy: "open" in om elk lid toe te staan (standaard nog steeds vermelding-gated).
• Stel channels.msteams.groupPolicy: "disabled" in om geen kanalen toe te staan.

Voorbeeld:

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

Teams + kanaal-allowlist

• Beperk groeps-/kanaalantwoorden door teams en kanalen op te nemen onder channels.msteams.teams.
• Sleutels moeten stabiele Teams-gespreks-ID's uit Teams-links gebruiken, geen veranderlijke weergavenamen.
• Wanneer groupPolicy="allowlist" en er een teams-allowlist aanwezig is, worden alleen vermelde teams/kanalen geaccepteerd (vermelding-gated).
• De configuratiewizard accepteert Team/Channel-items en slaat ze voor je op.
• Bij het opstarten zet OpenClaw team-/kanaal- en gebruikers-allowlistnamen om naar ID's (wanneer Graph-machtigingen dit toestaan) en logt de mapping; niet-omgezette team-/kanaalnamen blijven bewaard zoals getypt, maar worden standaard genegeerd voor routing tenzij channels.msteams.dangerouslyAllowNameMatching: true is ingeschakeld.

Voorbeeld:

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

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

Gefedereerde authenticatie (certificaat plus managed identity)

Toegevoegd in 2026.4.11

Voor productie-implementaties ondersteunt OpenClaw gefedereerde authenticatie als veiliger alternatief voor clientsecrets. Er zijn twee methoden beschikbaar:

Optie A: Certificaatgebaseerde authenticatie

Gebruik een PEM-certificaat dat is geregistreerd bij je Entra ID-appregistratie.

Configuratie:

1. Genereer of verkrijg een certificaat (PEM-indeling met private key).
2. In Entra ID → App Registration → Certificates & secrets → Certificates → upload het openbare certificaat.

Config:

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

Env vars:

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

Optie B: Azure Managed Identity

Gebruik Azure Managed Identity voor wachtwoordloze authenticatie. Dit is ideaal voor implementaties op Azure-infrastructuur (AKS, App Service, Azure-VM's) waar een managed identity beschikbaar is.

Hoe het werkt:

1. De botpod/VM heeft een managed identity (system-assigned of user-assigned).
2. Een federated identity credential koppelt de managed identity aan de Entra ID-appregistratie.
3. Tijdens runtime gebruikt OpenClaw @azure/identity om tokens op te halen van het Azure IMDS-endpoint (169.254.169.254).
4. Het token wordt doorgegeven aan de Teams SDK voor botauthenticatie.

Vereisten:

• Azure-infrastructuur met ingeschakelde managed identity (AKS workload identity, App Service, VM)
• Federated identity credential gemaakt op de Entra ID-appregistratie
• Netwerktoegang tot IMDS (169.254.169.254:80) vanuit de pod/VM

Config (system-assigned managed identity):

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

Configuratie (door gebruiker toegewezen beheerde identiteit):

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

Omgevingsvariabelen:

• MSTEAMS_AUTH_TYPE=federated
• MSTEAMS_USE_MANAGED_IDENTITY=true
• MSTEAMS_MANAGED_IDENTITY_CLIENT_ID=<client-id> (alleen voor door gebruiker toegewezen)

AKS Workload Identity instellen

Voor AKS-implementaties die workloadidentiteit gebruiken:

1. Schakel workloadidentiteit in op je AKS-cluster.

2. Maak een federatieve identiteitsreferentie in de Entra ID-appregistratie:

   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. Annoteer het Kubernetes-serviceaccount met de appclient-ID:

   apiVersion: v1kind: ServiceAccountmetadata:  name: my-bot-sa  annotations:    azure.workload.identity/client-id: "<APP_CLIENT_ID>"

4. Label de pod voor injectie van workloadidentiteit:

   metadata:  labels:    azure.workload.identity/use: "true"

5. Zorg voor netwerktoegang tot IMDS (169.254.169.254) - als je NetworkPolicy gebruikt, voeg dan een egress-regel toe die verkeer naar 169.254.169.254/32 op poort 80 toestaat.

Vergelijking van authenticatietypes

Standaardgedrag: Wanneer authType niet is ingesteld, gebruikt OpenClaw standaard authenticatie met clientgeheim. Bestaande configuraties blijven zonder wijzigingen werken.

Lokale ontwikkeling (tunneling)

Teams kan localhost niet bereiken. Gebruik een persistente ontwikkeltunnel zodat je URL tussen sessies hetzelfde blijft:

# One-time setup:devtunnel create my-openclaw-bot --allow-anonymousdevtunnel port create my-openclaw-bot -p 3978 --protocol auto # Each dev session:devtunnel host my-openclaw-bot

Alternatieven: ngrok http 3978 of tailscale funnel 3978 (URL's kunnen per sessie veranderen).

Als je tunnel-URL verandert, werk dan het eindpunt bij:

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

De bot testen

Diagnostiek uitvoeren:

teams app doctor <teamsAppId>

Controleert botregistratie, AAD-app, manifest en SSO-configuratie in één keer.

Een testbericht verzenden:

1. Installeer de Teams-app (gebruik de installatielink van teams app get <id> --install-link)
2. Zoek de bot in Teams en stuur een DM
3. Controleer Gateway-logboeken op binnenkomende activiteit

Omgevingsvariabelen

Alle configuratiesleutels kunnen in plaats daarvan via omgevingsvariabelen worden ingesteld:

• MSTEAMS_APP_ID
• MSTEAMS_APP_PASSWORD
• MSTEAMS_TENANT_ID
• MSTEAMS_AUTH_TYPE (optioneel: "secret" of "federated")
• MSTEAMS_CERTIFICATE_PATH (federatief + certificaat)
• MSTEAMS_CERTIFICATE_THUMBPRINT (optioneel, niet vereist voor authenticatie)
• MSTEAMS_USE_MANAGED_IDENTITY (federatief + beheerde identiteit)
• MSTEAMS_MANAGED_IDENTITY_CLIENT_ID (alleen door gebruiker toegewezen MI)

Actie voor lidgegevens

OpenClaw biedt een door Graph ondersteunde member-info-actie voor Microsoft Teams, zodat agents en automatiseringen gegevens van kanaalleden (weergavenaam, e-mail, rol) rechtstreeks vanuit Microsoft Graph kunnen opzoeken.

Vereisten:

• Member.Read.Group RSC-machtiging (al opgenomen in het aanbevolen manifest)
• Voor opzoekacties tussen teams: User.Read.All Graph Application-machtiging met beheerderstoestemming

De actie wordt beheerd door channels.msteams.actions.memberInfo (standaard: ingeschakeld wanneer Graph-referenties beschikbaar zijn).

Geschiedeniscontext

• channels.msteams.historyLimit bepaalt hoeveel recente kanaal-/groepsberichten in de prompt worden opgenomen.
• Valt terug op messages.groupChat.historyLimit. Stel in op 0 om uit te schakelen (standaard 50).
• Opgehaalde threadgeschiedenis wordt gefilterd op allowlists voor afzenders (allowFrom / groupAllowFrom), zodat het vullen van threadcontext alleen berichten van toegestane afzenders bevat.
• Geciteerde bijlagecontext (afgeleid van Teams-antwoord-HTML met ReplyTo*) wordt momenteel doorgegeven zoals ontvangen.
• Met andere woorden: allowlists bepalen wie de agent kan activeren; alleen specifieke aanvullende contextpaden worden vandaag gefilterd.
• DM-geschiedenis kan worden beperkt met channels.msteams.dmHistoryLimit (gebruikersbeurten). Overrides per gebruiker: channels.msteams.dms["<user_id>"].historyLimit.

Huidige Teams RSC-machtigingen (manifest)

Dit zijn de bestaande resourceSpecific-machtigingen in ons Teams-appmanifest. Ze gelden alleen binnen het team/de chat waar de app is geïnstalleerd.

Voor kanalen (teambereik):

• ChannelMessage.Read.Group (Application) - alle kanaalberichten ontvangen zonder @vermelding
• ChannelMessage.Send.Group (Application)
• Member.Read.Group (Application)
• Owner.Read.Group (Application)
• ChannelSettings.Read.Group (Application)
• TeamMember.Read.Group (Application)
• TeamSettings.Read.Group (Application)

Voor groepschats:

• ChatMessage.Read.Chat (Application) - alle groepschatberichten ontvangen zonder @vermelding

RSC-machtigingen toevoegen via de Teams CLI:

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

Voorbeeld van Teams-manifest (geredigeerd)

Minimaal, geldig voorbeeld met de vereiste velden. Vervang ID's en URL's.

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

Manifestwaarschuwingen (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 bestandsafhandeling in persoonlijk bereik.
• authorization.permissions.resourceSpecific moet kanaallezen/-verzenden bevatten als je kanaalverkeer wilt.

Een bestaande app bijwerken

Een al geïnstalleerde Teams-app bijwerken (bijvoorbeeld om RSC-machtigingen toe te voegen):

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

Installeer de app na het bijwerken opnieuw in elk team zodat nieuwe machtigingen van kracht worden, en sluit Teams volledig af en start het opnieuw (niet alleen het venster sluiten) om gecachte appmetadata te wissen.

Mogelijkheden: alleen RSC versus Graph

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

Werkt:

• Tekstinhoud van kanaalberichten lezen.
• Tekstinhoud van kanaalberichten verzenden.
• Bestandsbijlagen voor persoonlijke (DM) berichten ontvangen.

Werkt NIET:

• 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-gebeurtenis).

Met Teams RSC + Microsoft Graph Application-machtigingen

Voegt toe:

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

RSC versus Graph API

Kortom: RSC is voor realtime luisteren; Graph API is voor historische toegang. Om gemiste berichten in te halen terwijl je offline was, heb je Graph API nodig met ChannelMessage.Read.All (vereist beheerderstoestemming).

Media + geschiedenis met Graph ingeschakeld (vereist voor kanalen)

Als je afbeeldingen/bestanden in kanalen nodig hebt of berichtgeschiedenis wilt ophalen, moet je Microsoft Graph-machtigingen inschakelen en beheerderstoestemming verlenen.

1. Voeg in Entra ID (Azure AD) App Registration Microsoft Graph Application-machtigingen toe:
   • ChannelMessage.Read.All (kanaalbijlagen + geschiedenis)
   • Chat.Read.All of ChatMessage.Read.All (groepschats)
2. Verleen beheerderstoestemming voor de tenant.
3. Verhoog de manifestversie van de Teams-app, upload opnieuw en installeer de app opnieuw in Teams.
4. Sluit Teams volledig af en start het opnieuw om gecachte appmetadata te wissen.

Aanvullende machtiging voor gebruikersvermeldingen: @vermeldingen van gebruikers werken standaard voor gebruikers in het gesprek. Als je echter dynamisch gebruikers wilt zoeken en vermelden die niet in het huidige gesprek zitten, voeg dan de machtiging User.Read.All (Application) toe en verleen beheerderstoestemming.

Bekende beperkingen

Webhook-time-outs

Teams levert berichten via HTTP-Webhook. Als verwerking te lang duurt (bijv. trage LLM-antwoorden), kun je het volgende zien:

• Gateway-time-outs
• Teams probeert het bericht opnieuw (waardoor duplicaten ontstaan)
• Weggevallen antwoorden

OpenClaw handelt dit af door snel terug te keren en antwoorden proactief te verzenden, maar zeer trage antwoorden kunnen nog steeds problemen veroorzaken.

Opmaak

Teams-markdown is beperkter dan Slack of Discord:

• Basisopmaak werkt: vet, cursief, code, links
• Complexe markdown (tabellen, geneste lijsten) wordt mogelijk niet correct weergegeven
• Adaptive Cards worden ondersteund voor peilingen en semantische presentatieverzendingen (zie hieronder)

Configuratie

Belangrijke instellingen (zie /gateway/configuration voor gedeelde kanaalpatronen):

• channels.msteams.enabled: schakel het kanaal in/uit.
• channels.msteams.appId, channels.msteams.appPassword, channels.msteams.tenantId: botreferenties.
• 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: DM-allowlist (AAD-object-ID's aanbevolen). De wizard zet namen om naar ID's tijdens de setup wanneer Graph-toegang beschikbaar is.
• channels.msteams.dangerouslyAllowNameMatching: noodschakelaar om veranderlijke UPN-/weergavenaam-matching en directe routering op team-/kanaalnaam opnieuw in te schakelen.
• channels.msteams.textChunkLimit: chunkgrootte voor uitgaande tekst.
• channels.msteams.chunkMode: length (standaard) of newline om te splitsen op lege regels (alineagrenzen) vóór chunking op lengte.
• channels.msteams.mediaAllowHosts: allowlist voor hosts van inkomende bijlagen (standaard Microsoft-/Teams-domeinen).
• channels.msteams.mediaAuthAllowHosts: allowlist voor het toevoegen van Authorization-headers bij media-retries (standaard Graph- en Bot Framework-hosts).
• channels.msteams.requireMention: vereis @mention in kanalen/groepen (standaard true).
• channels.msteams.replyStyle: thread | top-level (zie Antwoordstijl).
• channels.msteams.teams.<teamId>.replyStyle: override per team.
• channels.msteams.teams.<teamId>.requireMention: override per team.
• channels.msteams.teams.<teamId>.tools: standaard overrides voor toolbeleid per team (allow/deny/alsoAllow) die worden gebruikt wanneer een kanaaloverride ontbreekt.
• channels.msteams.teams.<teamId>.toolsBySender: standaard overrides voor toolbeleid per team per afzender ("*" wildcard ondersteund).
• channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle: override per kanaal.
• channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention: override per kanaal.
• channels.msteams.teams.<teamId>.channels.<conversationId>.tools: overrides voor toolbeleid per kanaal (allow/deny/alsoAllow).
• channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender: overrides voor toolbeleid per kanaal per afzender ("*" wildcard ondersteund).
• toolsBySender-sleutels moeten expliciete prefixes gebruiken: channel:, id:, e164:, username:, name: (verouderde sleutels zonder prefix worden nog steeds alleen naar id: gemapt).
• channels.msteams.actions.memberInfo: schakel de door Graph ondersteunde actie voor ledeninformatie in of uit (standaard: ingeschakeld wanneer Graph-referenties beschikbaar zijn).
• channels.msteams.authType: authenticatietype - "secret" (standaard) of "federated".
• channels.msteams.certificatePath: pad naar PEM-certificaatbestand (gefedereerde + certificaatauthenticatie).
• channels.msteams.certificateThumbprint: certificaatvingerafdruk (optioneel, niet vereist voor authenticatie).
• channels.msteams.useManagedIdentity: schakel authenticatie met managed identity in (gefedereerde modus).
• channels.msteams.managedIdentityClientId: client-ID voor door gebruiker toegewezen managed identity.
• channels.msteams.sharePointSiteId: SharePoint-site-ID voor bestandsuploads in groepschats/kanalen (zie Bestanden verzenden in groepschats).

Routering en sessies

• Sessiesleutels volgen de standaard agentindeling (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 versus berichten

Teams heeft onlangs twee kanaal-UI-stijlen geïntroduceerd boven op hetzelfde onderliggende datamodel:

Het probleem: De Teams-API geeft niet vrij welke UI-stijl een kanaal gebruikt. Als je de verkeerde replyStyle gebruikt:

• thread in een kanaal met Threads-stijl → antwoorden verschijnen ongemakkelijk genest
• top-level in een kanaal met Berichten-stijl → antwoorden verschijnen als afzonderlijke berichten op topniveau in plaats van in de thread

Oplossing: Configureer replyStyle per kanaal op basis van hoe het kanaal is ingesteld:

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

Resolutievolgorde

Wanneer de bot een antwoord naar een kanaal verzendt, wordt replyStyle opgelost van de meest specifieke override naar de standaardwaarde. De eerste niet-undefined waarde wint:

1. Per kanaal — channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle
2. Per team — channels.msteams.teams.<teamId>.replyStyle
3. Globaal — channels.msteams.replyStyle
4. Impliciete standaard — afgeleid van requireMention:
   • requireMention: true → thread
   • requireMention: false → top-level

Als je requireMention: false globaal instelt zonder expliciete replyStyle, verschijnen vermeldingen in kanalen met Berichten-stijl als berichten op topniveau, zelfs wanneer de inkomende activiteit een threadantwoord was. Zet replyStyle: "thread" vast op globaal, team- of kanaalniveau om verrassingen te voorkomen.

Behoud van threadcontext

Wanneer replyStyle: "thread" actief is en de bot vanuit een kanaalthread is @mentioned, koppelt OpenClaw de oorspronkelijke threadroot opnieuw aan de uitgaande conversatiereferentie (19:…@thread.tacv2;messageid=<root>), zodat het antwoord in dezelfde thread terechtkomt. Dit geldt zowel voor liveverzendingen (binnen dezelfde beurt) als voor proactieve verzendingen nadat de Bot Framework-turncontext is verlopen (bijv. langlopende agents, antwoorden op wachtrijgezette tool-calls via mcp__openclaw__message).

De threadroot wordt gehaald uit de opgeslagen threadId op de conversatiereferentie. Oudere opgeslagen referenties van vóór threadId vallen terug op activityId (welke inkomende activiteit de conversatie het laatst heeft geïnitialiseerd), zodat bestaande implementaties blijven werken zonder opnieuw te initialiseren.

Wanneer replyStyle: "top-level" actief is, worden inkomende kanaalthreads bewust beantwoord als nieuwe berichten op topniveau — er wordt geen threadsuffix toegevoegd. Dit is het juiste gedrag voor kanalen met Threads-stijl; als je berichten op topniveau ziet waar je threadantwoorden verwachtte, is je replyStyle verkeerd ingesteld voor dat kanaal.

Bijlagen en afbeeldingen

Huidige beperkingen:

• DM's: Afbeeldingen en bestandsbijlagen werken via Teams-botbestands-API's.
• Kanalen/groepen: Bijlagen staan in M365-opslag (SharePoint/OneDrive). De webhook-payload bevat alleen een HTML-stub, niet de daadwerkelijke bestandsbytes. Graph API-machtigingen zijn vereist om kanaalbijlagen te downloaden.
• Gebruik voor expliciete file-first verzendingen action=upload-file met media / filePath / path; optioneel message wordt de begeleidende tekst/opmerking, en filename overschrijft de geüploade naam.

Zonder Graph-machtigingen worden kanaalberichten met afbeeldingen alleen als tekst ontvangen (de afbeeldingsinhoud is niet toegankelijk voor de bot). Standaard downloadt OpenClaw alleen media van Microsoft-/Teams-hostnamen. Overschrijf dit met channels.msteams.mediaAllowHosts (gebruik ["*"] om elke host toe te staan). Authorization-headers worden alleen toegevoegd voor hosts in channels.msteams.mediaAuthAllowHosts (standaard Graph- en Bot Framework-hosts). Houd deze lijst strikt (vermijd multi-tenant suffixen).

Bestanden verzenden in groepschats

Bots kunnen bestanden in DM's verzenden via de FileConsentCard-flow (ingebouwd). Bestanden verzenden in groepschats/kanalen vereist echter extra setup:

Waarom groepschats SharePoint nodig hebben

Bots hebben geen persoonlijke OneDrive-schijf (het Graph API-eindpunt /me/drive werkt niet voor applicatie-identiteiten). Om bestanden in groepschats/kanalen te verzenden, uploadt de bot naar een SharePoint-site en maakt een deellink.

Setup

1. Voeg Graph API-machtigingen toe in Entra ID (Azure AD) → App-registratie:

   • Sites.ReadWrite.All (Application) - bestanden uploaden naar SharePoint
   • Chat.Read.All (Application) - optioneel, schakelt deellinks per gebruiker in

2. Verleen beheerdersconsent 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",    },  },}

Deelgedrag

Delen per gebruiker is veiliger, omdat alleen de chatdeelnemers toegang hebben tot het bestand. Als de machtiging Chat.Read.All ontbreekt, valt de bot terug op organisatiebreed delen.

Fallbackgedrag

Locatie van opgeslagen bestanden

Geüploade bestanden worden opgeslagen in een map /OpenClawShared/ in de standaarddocumentbibliotheek van de geconfigureerde SharePoint-site.

Peilingen (Adaptive Cards)

OpenClaw verzendt Teams-peilingen als Adaptive Cards (er is geen native Teams-peiling-API).

• 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 vast te leggen.
• Peilingen plaatsen nog niet automatisch samenvattingen van resultaten (inspecteer indien nodig het opslagbestand).

Presentatiekaarten

Stuur semantische presentatiepayloads naar Teams-gebruikers of gesprekken met de message-tool of CLI. OpenClaw rendert ze als Teams Adaptive Cards vanuit het generieke presentatiecontract.

De parameter presentation accepteert semantische blokken. Wanneer presentation is opgegeven, is de berichttekst optioneel.

Agent-tool:

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

CLI:

openclaw message send --channel msteams \  --target "conversation:19:[email protected]" \  --presentation '{"title":"Hello","blocks":[{"type":"text","text":"Hello!"}]}'

Zie Doelindelingen hieronder voor details over de doelindeling.

Doelindelingen

MSTeams-doelen gebruiken prefixen om onderscheid te maken tussen gebruikers en gesprekken:

CLI-voorbeelden:

# Send to a user by IDopenclaw 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 channelopenclaw message send --channel msteams --target "conversation:19:[email protected]" --message "Hello" # Send a presentation card to a conversationopenclaw message send --channel msteams --target "conversation:19:[email protected]" \  --presentation '{"title":"Hello","blocks":[{"type":"text","text":"Hello"}]}'

Voorbeelden voor Agent-tools:

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

{  action: "send",  channel: "msteams",  target: "conversation:19:[email protected]",  presentation: {    title: "Hello",    blocks: [{ type: "text", text: "Hello" }],  },}

Proactieve berichten

• Proactieve berichten zijn alleen mogelijk nadat een gebruiker interactie heeft gehad, omdat we op dat moment gespreksreferenties opslaan.
• Zie /gateway/configuration voor dmPolicy en gating via allowlist.

Team- en kanaal-ID's (veelvoorkomende valkuil)

De queryparameter groupId in Teams-URL's is NIET de team-ID die voor configuratie wordt gebruikt. Haal ID's in plaats daarvan uit het URL-pad:

Team-URL:

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

Kanaal-URL:

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

Voor configuratie:

• Teamsleutel = padsegment na /team/ (URL-gedecodeerd, bijvoorbeeld 19:[email protected]; oudere tenants kunnen @thread.skype tonen, wat ook geldig is)
• Kanaalsleutel = padsegment na /channel/ (URL-gedecodeerd)
• Negeer de queryparameter groupId voor OpenClaw-routering. Dit is de Microsoft Entra-groeps-ID, niet de Bot Framework-gespreks-ID die wordt gebruikt in inkomende Teams-activiteiten.

Privékanalen

Bots hebben beperkte ondersteuning in privékanalen:

Workarounds als privékanalen niet werken:

1. Gebruik standaardkanalen voor botinteracties
2. Gebruik DM's - gebruikers kunnen de bot altijd rechtstreeks een bericht sturen
3. Gebruik Graph API voor historische toegang (vereist ChannelMessage.Read.All)

Probleemoplossing

Veelvoorkomende problemen

• Afbeeldingen worden niet weergegeven in kanalen: Graph-machtigingen of beheerderstoestemming ontbreken. Installeer de Teams-app opnieuw en sluit Teams volledig af en open het opnieuw.
• Geen reacties in kanaal: vermeldingen zijn standaard vereist; stel channels.msteams.requireMention=false in of configureer dit per team/kanaal.
• Versiemismatch (Teams toont nog steeds oud manifest): verwijder de app, voeg deze opnieuw toe en sluit Teams volledig af om te vernieuwen.
• 401 Unauthorized van Webhook: verwacht bij handmatig testen zonder Azure JWT - betekent dat het endpoint bereikbaar is, maar authenticatie is mislukt. Gebruik Azure Web Chat om correct te testen.

Fouten bij manifestupload

• "Icon file cannot be empty": Het manifest verwijst naar pictogrambestanden van 0 bytes. Maak geldige PNG-pictogrammen (32x32 voor outline.png, 192x192 voor color.png).
• "webApplicationInfo.Id already in use": De app is nog geïnstalleerd in een ander team/chat. Zoek en verwijder die installatie eerst, of wacht 5-10 minuten op propagatie.
• "Something went wrong" bij uploaden: Upload in plaats daarvan via https://admin.teams.microsoft.com, open browser-DevTools (F12) → tabblad Network en controleer de response-body op de daadwerkelijke fout.
• Sideload mislukt: Probeer "Upload an app to your org's app catalog" in plaats van "Upload a custom app" - dit omzeilt vaak sideload-beperkingen.

RSC-machtigingen werken niet

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

Verwijzingen

• Azure Bot maken - installatiehandleiding voor Azure Bot
• Teams Developer Portal - Teams-apps maken/beheren
• Teams-appmanifestschema
• Kanaalberichten ontvangen met RSC
• Referentie voor RSC-machtigingen
• Bestandsafhandeling voor Teams-bots (kanaal/groep vereist Graph)
• Proactieve berichten
• @microsoft/teams.cli - Teams CLI voor botbeheer

Gerelateerd

• Overzicht van kanalen - alle ondersteunde kanalen
• Koppelen - DM-authenticatie en koppelingsflow
• Groepen - groepschatgedrag en gating op vermeldingen
• Kanaalroutering - sessieroutering voor berichten
• Beveiliging - toegangsmodel en hardening