Microsoft Teams

​

Plugin incluso

openclaw plugins install @openclaw/msteams

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

​

Configurazione rapida

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"

• Crea un’applicazione Entra ID (Azure AD)
• Genera un client secret
• Compila e carica un manifesto dell’app Teams (con icone)
• Registra il bot (gestito da Teams per impostazione predefinita - nessuna sottoscrizione Azure necessaria)

{
  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>

​

Obiettivi

• Parlare con OpenClaw tramite DM, chat di gruppo o canali Teams.
• Mantenere il routing deterministico: le risposte tornano sempre al canale da cui sono arrivate.
• Usare per impostazione predefinita un comportamento sicuro del canale (menzioni richieste salvo configurazione diversa).

​

Scritture di configurazione

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

​

Controllo accessi (DM + gruppi)

• Predefinito: channels.msteams.dmPolicy = "pairing". I mittenti sconosciuti vengono ignorati finché non sono approvati.
• channels.msteams.allowFrom dovrebbe usare ID oggetto AAD stabili o gruppi statici di accesso mittenti come accessGroup:core-team.
• Non fare affidamento sulla corrispondenza UPN/nome visualizzato per le allowlist: possono cambiare. OpenClaw disabilita per impostazione predefinita la corrispondenza diretta dei nomi; abilitala esplicitamente con channels.msteams.dangerouslyAllowNameMatching: true.
• La procedura guidata può risolvere i nomi in ID tramite Microsoft Graph quando le credenziali lo consentono.

• Predefinito: channels.msteams.groupPolicy = "allowlist" (bloccato salvo aggiunta di groupAllowFrom). Usa channels.defaults.groupPolicy per sovrascrivere il valore predefinito quando non è impostato.
• channels.msteams.groupAllowFrom controlla quali mittenti o gruppi statici di accesso mittenti possono attivare nelle chat/canali di gruppo (ricade su channels.msteams.allowFrom).
• Imposta groupPolicy: "open" per consentire qualsiasi membro (ancora con gate tramite menzione per impostazione predefinita).
• Per consentire nessun canale, imposta channels.msteams.groupPolicy: "disabled".

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

• Limita l’ambito delle risposte di gruppo/canale elencando team e canali sotto channels.msteams.teams.
• Le chiavi dovrebbero usare ID conversazione Teams stabili dai link Teams, non nomi visualizzati modificabili.
• Quando groupPolicy="allowlist" e una allowlist di team è presente, vengono accettati solo i team/canali elencati (con gate tramite menzione).
• La procedura guidata di configurazione accetta voci Team/Channel e le memorizza per te.
• All’avvio, OpenClaw risolve i nomi allowlist di team/canali e utenti in ID (quando le autorizzazioni Graph lo consentono) e registra la mappatura; i nomi team/canale non risolti vengono mantenuti come digitati ma ignorati per il routing per impostazione predefinita, salvo abilitazione di channels.msteams.dangerouslyAllowNameMatching: true.

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

​

Autenticazione federata (certificato più managed identity)

Aggiunta in 2026.4.11

​

Opzione A: autenticazione basata su certificato

1. Genera o ottieni un certificato (formato PEM con chiave privata).
2. In Entra ID → App Registration → Certificates & secrets → Certificates → carica il certificato pubblico.

{
  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

​

Opzione B: Azure Managed Identity

1. Il pod/VM del bot ha una managed identity (assegnata dal sistema o assegnata dall’utente).
2. Una credenziale di identità federata collega la managed identity alla registrazione dell’app Entra ID.
3. A runtime, OpenClaw usa @azure/identity per acquisire token dall’endpoint Azure IMDS (169.254.169.254).
4. Il token viene passato al Teams SDK per l’autenticazione del bot.

• Infrastruttura Azure con managed identity abilitata (AKS workload identity, App Service, VM)
• Credenziale di identità federata creata sulla registrazione dell’app Entra ID
• Accesso di rete a IMDS (169.254.169.254:80) dal pod/VM

{
  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> (solo per assegnata dall’utente)

​

Configurazione di AKS Workload Identity

1. Abilita Workload Identity nel tuo cluster AKS.
2. Crea una credenziale di identità federata nella registrazione dell’app 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. Annota l’account di servizio Kubernetes con l’ID client dell’app:
   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: my-bot-sa
     annotations:
       azure.workload.identity/client-id: "<APP_CLIENT_ID>"
   
4. Etichetta il pod per l’iniezione di Workload Identity:
   metadata:
     labels:
       azure.workload.identity/use: "true"
   
5. Assicurati che l’accesso di rete a IMDS (169.254.169.254) sia disponibile: se usi NetworkPolicy, aggiungi una regola di uscita che consenta il traffico verso 169.254.169.254/32 sulla porta 80.

​

Confronto dei tipi di autenticazione

​

Sviluppo locale (tunneling)

# Configurazione iniziale:
devtunnel create my-openclaw-bot --allow-anonymous
devtunnel port create my-openclaw-bot -p 3978 --protocol auto

# Ogni sessione di sviluppo:
devtunnel host my-openclaw-bot

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

​

Test del Bot

teams app doctor <teamsAppId>

1. Installa l’app Teams (usa il link di installazione da teams app get <id> --install-link)
2. Trova il bot in Teams e invia un DM
3. Controlla i log del Gateway per l’attività in ingresso

​

Variabili d’ambiente

• MSTEAMS_APP_ID
• MSTEAMS_APP_PASSWORD
• MSTEAMS_TENANT_ID
• MSTEAMS_AUTH_TYPE (facoltativo: "secret" o "federated")
• MSTEAMS_CERTIFICATE_PATH (federated + certificato)
• MSTEAMS_CERTIFICATE_THUMBPRINT (facoltativo, non richiesto per l’autenticazione)
• MSTEAMS_USE_MANAGED_IDENTITY (federated + managed identity)
• MSTEAMS_MANAGED_IDENTITY_CLIENT_ID (solo MI assegnata dall’utente)

​

Azione informazioni membro

• Autorizzazione RSC Member.Read.Group (già nel manifest consigliato)
• Per ricerche tra team diversi: autorizzazione Graph Application User.Read.All con consenso dell’amministratore

​

Contesto della cronologia

• channels.msteams.historyLimit controlla quanti messaggi recenti di canale/gruppo vengono inclusi nel prompt.
• Ripiega su messages.groupChat.historyLimit. Imposta 0 per disabilitare (predefinito 50).
• La cronologia dei thread recuperata viene filtrata in base agli elenchi di mittenti consentiti (allowFrom / groupAllowFrom), quindi l’inizializzazione del contesto del thread include solo i messaggi dei mittenti consentiti.
• Il contesto degli allegati citati (ReplyTo* derivato dall’HTML delle risposte di Teams) viene attualmente passato così come ricevuto.
• In altre parole, gli elenchi di consentiti regolano chi può attivare l’agente; oggi vengono filtrati solo specifici percorsi di contesto supplementare.
• La cronologia dei DM può essere limitata con channels.msteams.dmHistoryLimit (turni utente). Override per utente: channels.msteams.dms["<user_id>"].historyLimit.

​

Autorizzazioni RSC Teams correnti (manifest)

• ChannelMessage.Read.Group (Application) - ricevere tutti i messaggi del canale senza @menzione
• 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) - ricevere tutti i messaggi della chat di gruppo senza @menzione

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

​

Esempio di manifest Teams (redatto)

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

​

Avvertenze sul manifest (campi obbligatori)

• bots[].botId deve corrispondere all’Azure Bot App ID.
• webApplicationInfo.id deve corrispondere all’Azure Bot App ID.
• bots[].scopes deve includere le superfici che prevedi di usare (personal, team, groupChat).
• bots[].supportsFiles: true è richiesto per la gestione dei file nell’ambito personale.
• authorization.permissions.resourceSpecific deve includere lettura/invio dei canali se vuoi traffico dei canali.

​

Aggiornare un’app esistente

# 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

​

Funzionalità: solo RSC vs Graph

​

Con solo Teams RSC (app installata, nessuna autorizzazione Graph API)

• Lettura del contenuto testuale dei messaggi del canale.
• Invio di contenuto testuale nei messaggi del canale.
• Ricezione di allegati file personali (DM).

• Contenuti di immagini o file di canali/gruppi (il payload include solo uno stub HTML).
• Download di allegati archiviati in SharePoint/OneDrive.
• Lettura della cronologia dei messaggi (oltre l’evento Webhook live).

​

Con Teams RSC + autorizzazioni Microsoft Graph Application

• Download dei contenuti ospitati (immagini incollate nei messaggi).
• Download di allegati file archiviati in SharePoint/OneDrive.
• Lettura della cronologia dei messaggi di canali/chat tramite Graph.

​

RSC vs Graph API

​

Media e cronologia abilitati da Graph (richiesti per i canali)

1. In Entra ID (Azure AD) Registrazione app, aggiungi le autorizzazioni Application Microsoft Graph:
   • ChannelMessage.Read.All (allegati del canale + cronologia)
   • Chat.Read.All o ChatMessage.Read.All (chat di gruppo)
2. Concedi il consenso dell’amministratore per il tenant.
3. Incrementa la versione del manifest dell’app Teams, ricaricalo e reinstalla l’app in Teams.
4. Chiudi completamente e riavvia Teams per cancellare i metadati dell’app memorizzati nella cache.

​

Limitazioni note

​

Timeout dei Webhook

• Timeout del Gateway
• Teams che riprova il messaggio (causando duplicati)
• Risposte perse

​

Supporto per il cloud di Teams e l’URL del servizio

• channels.msteams.cloud seleziona il preset cloud di Teams SDK per autenticazione, validazione JWT, servizi token e ambito Graph.
• channels.msteams.serviceUrl seleziona il limite dell’endpoint Bot Connector usato per validare i riferimenti alla conversazione archiviati prima di invii, modifiche, eliminazioni, schede, sondaggi, messaggi di consenso ai file e risposte accodate di lunga durata proattivi. È obbligatorio per i cloud SDK USGov e DoD. Per China/21Vianet, OpenClaw usa il preset SDK China e accetta URL di servizio archiviati/configurati solo sugli host del canale 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"
    }
  }
}

​

Formattazione

• La formattazione di base funziona: grassetto, corsivo, code, link
• Il markdown complesso (tabelle, elenchi annidati) potrebbe non essere renderizzato correttamente
• Le Adaptive Cards sono supportate per sondaggi e invii di presentazione semantica (vedi sotto)

​

Configurazione

• channels.msteams.enabled: abilita/disabilita il canale.
• channels.msteams.appId, channels.msteams.appPassword, channels.msteams.tenantId: credenziali del bot.
• channels.msteams.cloud: ambiente cloud Teams SDK (Public, USGov, USGovDoD o China; predefinito Public). Impostalo con serviceUrl per i cloud SDK USGov/DoD; China usa il preset SDK e i riferimenti alla conversazione Azure China Bot Framework archiviati, con gli helper basati su Graph disabilitati finché non sarà implementato l’instradamento Azure China Graph.
• channels.msteams.serviceUrl: limite dell’URL di servizio Bot Connector per le operazioni proattive SDK. Il cloud pubblico usa il valore predefinito SDK; impostalo per GCC (https://smba.infra.gcc.teams.microsoft.com/teams), GCC High o DoD. China accetta host del canale Azure China Bot Framework quando il riferimento alla conversazione archiviato proviene da Teams gestito da 21Vianet.
• channels.msteams.webhook.port (predefinito 3978)
• channels.msteams.webhook.path (predefinito /api/messages)
• channels.msteams.dmPolicy: pairing | allowlist | open | disabled (predefinito: pairing)
• channels.msteams.allowFrom: allowlist DM (ID oggetto AAD consigliati). La procedura guidata risolve i nomi in ID durante la configurazione quando è disponibile l’accesso a Graph.
• channels.msteams.dangerouslyAllowNameMatching: interruttore di emergenza per riabilitare la corrispondenza di UPN/nome visualizzato mutabili e l’instradamento diretto per nome di team/canale.
• channels.msteams.textChunkLimit: dimensione dei blocchi di testo in uscita.
• channels.msteams.chunkMode: length (predefinito) o newline per dividere su righe vuote (limiti di paragrafo) prima del chunking per lunghezza.
• channels.msteams.mediaAllowHosts: allowlist per gli host degli allegati in ingresso (per impostazione predefinita domini Microsoft/Teams).
• channels.msteams.mediaAuthAllowHosts: allowlist per allegare intestazioni Authorization ai tentativi successivi sui media (per impostazione predefinita host Graph + Bot Framework).
• channels.msteams.requireMention: richiede @mention in canali/gruppi (predefinito true).
• channels.msteams.replyStyle: thread | top-level (vedi Stile di risposta).
• channels.msteams.teams.<teamId>.replyStyle: override per team.
• channels.msteams.teams.<teamId>.requireMention: override per team.
• channels.msteams.teams.<teamId>.tools: override predefiniti per team dei criteri degli strumenti (allow/deny/alsoAllow) usati quando manca un override del canale.
• channels.msteams.teams.<teamId>.toolsBySender: override predefiniti per team e per mittente dei criteri degli strumenti (carattere jolly "*" supportato).
• channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle: override per canale.
• channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention: override per canale.
• channels.msteams.teams.<teamId>.channels.<conversationId>.tools: override per canale dei criteri degli strumenti (allow/deny/alsoAllow).
• channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender: override per canale e per mittente dei criteri degli strumenti (carattere jolly "*" supportato).
• Le chiavi toolsBySender devono usare prefissi espliciti: channel:, id:, e164:, username:, name: (le chiavi legacy senza prefisso continuano a mappare solo a id:).
• channels.msteams.actions.memberInfo: abilita o disabilita l’azione di informazioni sul membro basata su Graph (predefinito: abilitata quando sono disponibili le credenziali Graph).
• channels.msteams.authType: tipo di autenticazione - "secret" (predefinito) o "federated".
• channels.msteams.certificatePath: percorso del file di certificato PEM (autenticazione federata + certificato).
• channels.msteams.certificateThumbprint: identificazione personale del certificato (facoltativa, non obbligatoria per l’autenticazione).
• channels.msteams.useManagedIdentity: abilita l’autenticazione con identità gestita (modalità federata).
• channels.msteams.managedIdentityClientId: ID client per l’identità gestita assegnata dall’utente.
• channels.msteams.sharePointSiteId: ID del sito SharePoint per i caricamenti di file in chat di gruppo/canali (vedi Inviare file nelle chat di gruppo).

​

Instradamento e sessioni

• Le chiavi di sessione seguono il formato agente standard (vedi /concepts/session):
  • I messaggi diretti condividono la sessione principale (agent:<agentId>:<mainKey>).
  • I messaggi di canale/gruppo usano l’ID conversazione:
    • agent:<agentId>:msteams:channel:<conversationId>
    • agent:<agentId>:msteams:group:<conversationId>

​

Stile di risposta: thread vs post

• thread in un canale in stile Thread → le risposte appaiono annidate in modo poco naturale
• top-level in un canale in stile Post → le risposte appaiono come post separati di primo livello invece che nel thread

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

​

Precedenza di risoluzione

1. Per canale — channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle
2. Per team — channels.msteams.teams.<teamId>.replyStyle
3. Globale — channels.msteams.replyStyle
4. Predefinito implicito — derivato da requireMention:
   • requireMention: true → thread
   • requireMention: false → top-level

​

Conservazione del contesto del thread

​

Allegati e immagini

• DM: le immagini e gli allegati file funzionano tramite le API file del bot Teams.
• Canali/gruppi: gli allegati risiedono nello storage M365 (SharePoint/OneDrive). Il payload del Webhook include solo uno stub HTML, non i byte effettivi del file. Sono richieste autorizzazioni Graph API per scaricare gli allegati dei canali.
• Per invii espliciti con file come contenuto principale, usa action=upload-file con media / filePath / path; il message facoltativo diventa il testo/commento di accompagnamento e filename sovrascrive il nome caricato.

​

Invio di file nelle chat di gruppo

​

Perché le chat di gruppo richiedono SharePoint

​

Configurazione

1. Aggiungi autorizzazioni Graph API in Entra ID (Azure AD) → Registrazione app:
   • Sites.ReadWrite.All (Application) - caricare file su SharePoint
   • Chat.Read.All (Application) - facoltativo, abilita link di condivisione per utente
2. Concedi il consenso amministratore per il tenant.
3. Ottieni l’ID del sito 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. Configura OpenClaw:
   {
     channels: {
       msteams: {
         // ... other config ...
         sharePointSiteId: "contoso.sharepoint.com,guid1,guid2",
       },
     },
   }
   

​

Comportamento di condivisione

​

Comportamento di fallback

​

Posizione dei file archiviati

​

Sondaggi (Adaptive Cards)

• CLI: openclaw message poll --channel msteams --target conversation:<id> ...
• I voti vengono registrati dal Gateway nello SQLite dello stato Plugin di OpenClaw in state/openclaw.sqlite.
• I file msteams-polls.json esistenti vengono importati da openclaw doctor --fix, non dal Plugin in esecuzione.
• Il Gateway deve rimanere online per registrare i voti.
• I sondaggi non pubblicano ancora automaticamente riepiloghi dei risultati e non esiste ancora una CLI supportata per i risultati dei sondaggi.

​

Schede di presentazione

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

​

Formati target

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

​

Messaggistica proattiva

• I messaggi proattivi sono possibili solo dopo che un utente ha interagito, perché a quel punto archiviamo i riferimenti alla conversazione.
• Vedi /gateway/configuration per dmPolicy e il gating tramite allowlist.

​

ID team e canale (errore comune)

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)

• Chiave team = segmento del percorso dopo /team/ (decodificato da URL, ad es. 19:Bk4j...@thread.tacv2; i tenant più vecchi possono mostrare @thread.skype, anch’esso valido)
• Chiave canale = segmento del percorso dopo /channel/ (decodificato da URL)
• Ignora il parametro di query groupId per il routing OpenClaw. È l’ID gruppo Microsoft Entra, non l’ID conversazione Bot Framework usato nelle attività Teams in ingresso.

​

Canali privati

1. Usa canali standard per le interazioni con il bot
2. Usa i DM: gli utenti possono sempre inviare messaggi direttamente al bot
3. Usa Graph API per l’accesso storico (richiede ChannelMessage.Read.All)

​

Risoluzione dei problemi

​

Problemi comuni

• Immagini non visualizzate nei canali: autorizzazioni Graph o consenso amministratore mancanti. Reinstalla l’app Teams e chiudi/riapri completamente Teams.
• Nessuna risposta nel canale: le menzioni sono richieste per impostazione predefinita; imposta channels.msteams.requireMention=false o configura per team/canale.
• Mancata corrispondenza di versione (Teams mostra ancora il vecchio manifest): rimuovi e riaggiungi l’app, quindi chiudi completamente Teams per aggiornare.
• 401 Unauthorized dal Webhook: previsto durante il test manuale senza Azure JWT: significa che l’endpoint è raggiungibile ma l’autenticazione non è riuscita. Usa Azure Web Chat per testare correttamente.

​

Errori di caricamento del manifest

• “Icon file cannot be empty”: il manifest fa riferimento a file icona da 0 byte. Crea icone PNG valide (32x32 per outline.png, 192x192 per color.png).
• “webApplicationInfo.Id already in use”: l’app è ancora installata in un altro team/chat. Trovala e disinstallala prima, oppure attendi 5-10 minuti per la propagazione.
• “Something went wrong” durante il caricamento: carica invece tramite https://admin.teams.microsoft.com, apri DevTools del browser (F12) → scheda Network e controlla il corpo della risposta per l’errore effettivo.
• Sideload non riuscito: prova “Upload an app to your org’s app catalog” invece di “Upload a custom app”: spesso aggira le restrizioni di sideload.

​

Autorizzazioni RSC non funzionanti

1. Verifica che webApplicationInfo.id corrisponda esattamente all’App ID del tuo bot
2. Carica di nuovo l’app e reinstallala nel team/chat
3. Controlla se l’amministratore della tua organizzazione ha bloccato le autorizzazioni RSC
4. Conferma di usare l’ambito corretto: ChannelMessage.Read.Group per i team, ChatMessage.Read.Chat per le chat di gruppo

​

Riferimenti

• Crea Azure Bot - guida alla configurazione di Azure Bot
• Portale per sviluppatori Teams - crea/gestisci app Teams
• Schema del manifesto dell’app Teams
• Ricevere messaggi di canale con RSC
• Riferimento autorizzazioni RSC
• Gestione dei file dei bot Teams (canale/gruppo richiede Graph)
• Messaggistica proattiva
• @microsoft/teams.cli - CLI Teams per la gestione dei bot

​

Correlati

• Panoramica dei canali - tutti i canali supportati
• Abbinamento - autenticazione tramite DM e flusso di abbinamento
• Gruppi - comportamento delle chat di gruppo e gating delle menzioni
• Instradamento dei canali - instradamento delle sessioni per i messaggi
• Sicurezza - modello di accesso e hardening