Microsoft Teams

​

Plugin incluído

openclaw plugins install @openclaw/msteams

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

​

Configuração rápida

npm install -g @microsoft/teams.cli@preview
teams login
teams status   # verifique se você está conectado e consulte as informações do seu locatário

# Configuração única (URL persistente entre sessões):
devtunnel create my-openclaw-bot --allow-anonymous
devtunnel port create my-openclaw-bot -p 3978 --protocol auto

# A cada sessão de desenvolvimento:
devtunnel host my-openclaw-bot
# Seu endpoint: https://<tunnel-id>.devtunnels.ms/api/messages

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

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

teams app get <teamsAppId> --install-link

teams app doctor <teamsAppId>

​

Objetivos

• Converse com o OpenClaw por meio de mensagens diretas, chats em grupo ou canais do Teams.
• Mantenha o roteamento determinístico: as respostas sempre retornam ao canal de origem.
• Use por padrão um comportamento seguro nos canais (menções obrigatórias, salvo configuração em contrário).

​

Gravações de configuração

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

​

Controle de acesso (mensagens diretas + grupos)

• Padrão: channels.msteams.dmPolicy = "pairing". Remetentes desconhecidos são ignorados até serem aprovados.
• channels.msteams.allowFrom deve usar IDs de objeto AAD estáveis ou grupos estáticos de acesso de remetentes, como accessGroup:core-team.
• Não dependa da correspondência por UPN/nome de exibição para listas de permissões; eles podem mudar. O OpenClaw desativa por padrão a correspondência direta por nome; habilite-a com channels.msteams.dangerouslyAllowNameMatching: true.
• O assistente pode resolver nomes em IDs por meio do Microsoft Graph quando as credenciais permitirem.

• Padrão: channels.msteams.groupPolicy = "allowlist" (bloqueado, a menos que você adicione groupAllowFrom). channels.defaults.groupPolicy pode substituir o padrão compartilhado quando channels.msteams.groupPolicy não estiver definido.
• channels.msteams.groupAllowFrom controla quais remetentes ou grupos estáticos de acesso de remetentes podem acionar o bot em chats em grupo/canais (usa channels.msteams.allowFrom como alternativa).
• Defina groupPolicy: "open" para permitir qualquer membro (a exigência de menção continua ativa por padrão).
• Para bloquear todos os canais, defina channels.msteams.groupPolicy: "disabled".

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

• Restrinja as respostas em grupos/canais listando equipes e canais em channels.msteams.teams.
• Use como chaves IDs de conversa estáveis do Teams obtidos dos links do Teams, e não nomes de exibição mutáveis (consulte IDs de equipe e canal).
• Quando groupPolicy="allowlist" e uma lista de permissões de equipes estiverem presentes, somente as equipes/os canais listados serão aceitos (com exigência de menção).
• O assistente de configuração aceita entradas Team/Channel e as armazena para você.
• Na inicialização, o OpenClaw resolve nomes de equipes/canais e de listas de permissões de usuários em IDs (quando as permissões do Graph permitem) e registra o mapeamento. Nomes não resolvidos são mantidos como digitados, mas ignorados para fins de roteamento, a menos que channels.msteams.dangerouslyAllowNameMatching: true esteja definido.

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

​

Autenticação federada (certificado mais identidade gerenciada)

​

Opção A: Autenticação baseada em certificado

1. Gere ou obtenha um certificado (formato PEM com chave privada).
2. Entra ID → App Registration → Certificates & secrets → Certificates → carregue o certificado público.

{
  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

​

Opção B: Identidade Gerenciada do Azure

1. O pod/a VM do bot tem uma identidade gerenciada (atribuída pelo sistema ou pelo usuário).
2. Uma credencial de identidade federada vincula a identidade gerenciada ao registro do aplicativo do Entra ID.
3. Em tempo de execução, o OpenClaw usa @azure/identity para adquirir tokens do endpoint IMDS do Azure.
4. O token é passado ao SDK do Teams para autenticação do bot.

• Infraestrutura do Azure com identidade gerenciada habilitada (identidade de carga de trabalho do AKS, App Service, VM).
• Credencial de identidade federada criada no registro de aplicativo do Entra ID.
• Acesso de rede ao IMDS (169.254.169.254:80) a partir do pod/VM.

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

• MSTEAMS_AUTH_TYPE=federated
• MSTEAMS_USE_MANAGED_IDENTITY=true
• MSTEAMS_MANAGED_IDENTITY_CLIENT_ID=<client-id> (somente atribuída pelo usuário)

​

Configuração da identidade de carga de trabalho do AKS

1. Habilite a identidade de carga de trabalho no cluster do AKS.
2. Crie uma credencial de identidade federada no registro de aplicativo do 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. Anote a conta de serviço do Kubernetes com a ID de cliente do aplicativo:
   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: my-bot-sa
     annotations:
       azure.workload.identity/client-id: "<APP_CLIENT_ID>"
   
4. Adicione um rótulo ao pod para a injeção da identidade de carga de trabalho:
   metadata:
     labels:
       azure.workload.identity/use: "true"
   
5. Permita o acesso de rede ao IMDS (169.254.169.254): se estiver usando NetworkPolicy, adicione uma regra de saída para 169.254.169.254/32 na porta 80.

​

Comparação dos tipos de autenticação

​

Desenvolvimento local (tunelamento)

# Configuração única:
devtunnel create my-openclaw-bot --allow-anonymous
devtunnel port create my-openclaw-bot -p 3978 --protocol auto

# A cada sessão de desenvolvimento:
devtunnel host my-openclaw-bot

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

​

Testando o bot

teams app doctor <teamsAppId>

1. Instale o aplicativo do Teams (link de instalação em teams app get <id> --install-link).
2. Encontre o bot no Teams e envie uma mensagem direta.
3. Verifique os logs do Gateway para conferir a atividade recebida.

​

Variáveis de ambiente

​

Ação de informações do membro

• Permissões RSC ChannelSettings.Read.Group e TeamMember.Read.Group (já incluídas no manifesto recomendado).

​

Contexto do histórico

• channels.msteams.historyLimit controla quantas mensagens recentes do canal/grupo são incluídas no prompt. Usa messages.groupChat.historyLimit como alternativa e, em seguida, o padrão de 50. Defina 0 para desabilitar.
• O histórico de threads obtido é filtrado pelas listas de remetentes permitidos (allowFrom / groupAllowFrom), portanto, a inclusão inicial do contexto da thread contém apenas mensagens de remetentes permitidos.
• O contexto de anexos citados (analisado a partir do HTML do esquema Skype Reply nos próprios anexos de uma resposta) é repassado sem filtragem; atualmente, somente a inclusão inicial do histórico da thread aplica o filtro da lista de remetentes permitidos.
• O histórico de mensagens diretas pode ser limitado com channels.msteams.dmHistoryLimit (turnos do usuário). Substituições por usuário: channels.msteams.dms["<user_id>"].historyLimit.

​

Permissões RSC atuais do Teams (manifesto)

• ChannelMessage.Read.Group (Aplicativo) - receber todas as mensagens do canal sem @menção
• ChannelMessage.Send.Group (Aplicativo)
• Member.Read.Group (Aplicativo)
• Owner.Read.Group (Aplicativo)
• ChannelSettings.Read.Group (Aplicativo)
• TeamMember.Read.Group (Aplicativo)
• TeamSettings.Read.Group (Aplicativo)

• ChatMessage.Read.Chat (Aplicativo) - receber todas as mensagens do chat em grupo sem @menção

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

​

Exemplo de manifesto do Teams (com dados ocultados)

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

​

Ressalvas do manifesto (campos obrigatórios)

• bots[].botId deve corresponder à ID do aplicativo do Azure Bot.
• webApplicationInfo.id deve corresponder à ID do aplicativo do Azure Bot.
• bots[].scopes deve incluir as superfícies que se pretende usar (personal, team, groupChat).
• bots[].supportsFiles: true é obrigatório para o processamento de arquivos no escopo pessoal.
• authorization.permissions.resourceSpecific deve incluir leitura/envio de canais para o tráfego dos canais.

​

Atualizando um aplicativo existente

# Baixe, edite e reenvie o manifesto
teams app manifest download <teamsAppId> manifest.json
# Edite manifest.json localmente...
teams app manifest upload manifest.json <teamsAppId>
# A versão é incrementada automaticamente se o conteúdo tiver sido alterado

​

Recursos: somente RSC versus Graph

​

Com somente RSC do Teams (aplicativo instalado, sem permissões da API do Graph)

• Ler o conteúdo de texto das mensagens do canal.
• Enviar conteúdo de texto nas mensagens do canal.
• Receber anexos de arquivos pessoais (mensagem direta).

• Conteúdo de imagens ou arquivos de canais/grupos (a carga inclui apenas um esboço em HTML).
• Baixar anexos armazenados no SharePoint/OneDrive.
• Ler o histórico de mensagens além do evento de Webhook em tempo real.

​

Com RSC do Teams + permissões de aplicativo do Microsoft Graph

• Baixar conteúdo hospedado (imagens coladas nas mensagens).
• Baixar anexos de arquivos armazenados no SharePoint/OneDrive.
• Ler o histórico de mensagens de canais/chats pelo Graph.

​

RSC versus API do Graph

​

Mídia + histórico habilitados pelo Graph

1. Entra ID (Azure AD) App Registration → adicione Application permissions do Graph:
   • ChannelMessage.Read.All para anexos e histórico de canais.
   • Chat.Read.All para anexos e histórico de chats em grupo.
   • Files.Read.All quando for necessário baixar os bytes de anexos do armazenamento do SharePoint/OneDrive; configurações somente de histórico não precisam dessa permissão.
2. Conceda Grant admin consent ao locatário.
3. Incremente a manifest version do aplicativo do Teams, faça o upload novamente e reinstale o aplicativo no Teams.
4. Encerre completamente e reinicie o Teams para limpar os metadados do aplicativo armazenados em cache.

​

Recuperação de arquivos de canais/grupos (graphMediaFallback)

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

​

Limitações conhecidas

​

Tempos limite do Webhook

• O Teams tentar entregar a mensagem novamente (causando duplicatas).
• Respostas descartadas.

​

Compatibilidade com nuvens do Teams e URLs de serviço

• channels.msteams.cloud seleciona a predefinição de nuvem do SDK do Teams para autenticação, validação JWT, serviços de token e escopo do Graph.
• channels.msteams.serviceUrl seleciona o limite do endpoint do Bot Connector usado para validar referências de conversa armazenadas antes de envios, edições, exclusões, cartões, enquetes, mensagens de consentimento para arquivos e respostas enfileiradas de longa duração proativos. É obrigatório para as nuvens USGov e DoD do SDK. Para China/21Vianet, o OpenClaw usa a predefinição China do SDK e aceita URLs de serviço armazenadas/configuradas somente em hosts de canal do 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"
    }
  }
}

​

Formatação

• A formatação básica funciona: negrito, itálico, code, links.
• Markdown complexo (tabelas, listas aninhadas) pode não ser renderizado corretamente.
• Adaptive Cards são compatíveis com enquetes e envios de apresentação semântica (veja abaixo).

​

Configuração

• channels.msteams.enabled: habilita/desabilita o canal.
• channels.msteams.appId, channels.msteams.appPassword, channels.msteams.tenantId: credenciais do bot.
• channels.msteams.cloud: ambiente de nuvem do SDK do Teams (Public, USGov, USGovDoD ou China; padrão Public). Defina com serviceUrl para nuvens do SDK USGov/DoD; a China usa a predefinição do SDK e referências de conversa armazenadas do Azure China Bot Framework, com auxiliares baseados no Graph desabilitados até que o roteamento do Azure China Graph seja disponibilizado.
• channels.msteams.serviceUrl: limite da URL do serviço Bot Connector para operações proativas do SDK. A nuvem pública usa o padrão do SDK; defina para GCC (https://smba.infra.gcc.teams.microsoft.com/teams), GCC High ou DoD. A China aceita hosts de canal do Azure China Bot Framework quando a referência de conversa armazenada vem do Teams operado pela 21Vianet.
• channels.msteams.webhook.port (padrão 3978).
• channels.msteams.webhook.path (padrão /api/messages).
• channels.msteams.dmPolicy: pairing | allowlist | open | disabled (padrão pairing).
• channels.msteams.allowFrom: lista de permissões de MDs (IDs de objeto do AAD recomendados). O assistente resolve nomes para IDs durante a configuração quando o acesso ao Graph está disponível.
• channels.msteams.dangerouslyAllowNameMatching: opção de emergência para reabilitar a correspondência mutável de UPN/nome de exibição e o roteamento direto por nome de equipe/canal.
• channels.msteams.textChunkLimit: tamanho dos segmentos de texto de saída em caracteres (padrão 4000, com limite máximo rígido de 4000, independentemente de um valor configurado maior).
• channels.msteams.streaming.chunkMode: length (padrão) ou newline para dividir em linhas em branco (limites de parágrafo) antes da segmentação por comprimento.
• channels.msteams.mediaAllowHosts: lista de permissões de hosts para anexos recebidos (o padrão são domínios da Microsoft/Teams: Graph, SharePoint/OneDrive, CDN do Teams, Bot Framework, Azure Media Services).
• channels.msteams.mediaAuthAllowHosts: lista de permissões para anexar cabeçalhos Authorization em novas tentativas de mídia (o padrão são hosts do Graph + Bot Framework).
• channels.msteams.graphMediaFallback: habilita consultas de mensagens no Graph quando o HTML do canal/grupo omite marcadores de arquivo (padrão false; consulte Recuperação de arquivos de canal/grupo).
• channels.msteams.mediaMaxMb: substituição do limite de tamanho de mídia por canal em MB. Usa agents.defaults.mediaMaxMb como alternativa quando não definido.
• channels.msteams.requireMention: exige @menção em canais/grupos (padrão true).
• channels.msteams.replyStyle: thread | top-level (consulte Estilo de resposta).
• channels.msteams.teams.<teamId>.replyStyle: substituição por equipe.
• channels.msteams.teams.<teamId>.requireMention: substituição por equipe.
• channels.msteams.teams.<teamId>.tools: substituições padrão da política de ferramentas por equipe (allow/deny/alsoAllow) usadas quando não há uma substituição de canal.
• channels.msteams.teams.<teamId>.toolsBySender: substituições padrão da política de ferramentas por equipe e por remetente (curinga "*" compatível).
• channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle: substituição por canal.
• channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention: substituição por canal.
• channels.msteams.teams.<teamId>.channels.<conversationId>.tools: substituições da política de ferramentas por canal (allow/deny/alsoAllow).
• channels.msteams.teams.<teamId>.channels.<conversationId>.toolsBySender: substituições da política de ferramentas por canal e por remetente (curinga "*" compatível).
• As chaves de toolsBySender devem usar prefixos explícitos: channel:, id:, e164:, username:, name: (chaves legadas sem prefixo ainda são mapeadas somente para id:).
• channels.msteams.authType: tipo de autenticação — "secret" (padrão) ou "federated".
• channels.msteams.certificatePath: caminho para o arquivo de certificado PEM (autenticação federada + certificado).
• channels.msteams.certificateThumbprint: impressão digital do certificado; aceita, mas não é obrigatória para autenticação.
• channels.msteams.useManagedIdentity: habilita a autenticação por identidade gerenciada (modo federado).
• channels.msteams.managedIdentityClientId: ID do cliente da identidade gerenciada atribuída pelo usuário.
• channels.msteams.sharePointSiteId: ID do site do SharePoint para uploads de arquivos em chats em grupo/canais (consulte Envio de arquivos em chats em grupo).
• channels.msteams.welcomeCard, channels.msteams.groupWelcomeCard, channels.msteams.promptStarters: Cartão Adaptável de boas-vindas exibido no primeiro contato por MD/grupo e seus botões de prompts sugeridos.
• channels.msteams.responsePrefix: texto adicionado como prefixo às respostas de saída.
• channels.msteams.feedbackEnabled (padrão true), channels.msteams.feedbackReflection (padrão true), channels.msteams.feedbackReflectionCooldownMs: feedback positivo/negativo nas respostas e o acompanhamento de reflexão sobre feedback negativo.
• channels.msteams.sso, channels.msteams.delegatedAuth: conexão OAuth do Bot Framework e escopos delegados do Graph para fluxos baseados em SSO; sso.enabled: true exige sso.connectionName.

​

Roteamento e sessões

• As chaves de sessão seguem o formato padrão do agente (consulte /concepts/session):
  • As mensagens diretas compartilham a sessão principal (agent:<agentId>:<mainKey>).
  • As mensagens de canal/grupo usam o ID da conversa:
    • agent:<agentId>:msteams:channel:<conversationId>
    • agent:<agentId>:msteams:group:<conversationId>

​

Estilo de resposta: threads versus publicações

• thread em um canal no estilo Threads → as respostas aparecem aninhadas de forma inadequada.
• top-level em um canal no estilo Publicações → as respostas aparecem como publicações separadas de nível superior, em vez de dentro da thread.

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

​

Precedência de resolução

1. Por canal — channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle
2. Por equipe — channels.msteams.teams.<teamId>.replyStyle
3. Global — channels.msteams.replyStyle
4. Padrão implícito — derivado de requireMention:
   • requireMention: true → thread
   • requireMention: false → top-level

​

Preservação do contexto da thread

​

Anexos e imagens

• MDs: imagens e anexos de arquivos funcionam por meio das APIs de arquivos de bot do Teams.
• Canais/grupos: os anexos ficam no armazenamento do M365 (SharePoint/OneDrive). A carga do Webhook inclui apenas um esboço HTML, não os bytes reais do arquivo. São necessárias permissões da API do Graph para baixar anexos de canais.
• Para envios explícitos que priorizam o arquivo, use action=upload-file com media / filePath / path; o message opcional torna-se o texto/comentário que acompanha o arquivo, e filename (ou title) substitui o nome do arquivo enviado.

​

Envio de arquivos em chats em grupo

​

Por que chats em grupo precisam do SharePoint

​

Configuração

1. Adicione permissões da API do Graph em Entra ID (Azure AD) → App Registration:
   • Sites.ReadWrite.All (Aplicativo) — faça upload de arquivos para o SharePoint.
   • ChatMember.Read.All (Aplicativo) — permissão de privilégio mínimo em todo o locatário para envios de arquivos em chats em grupo. Chat.Read.All também funciona e já oferece essa cobertura quando o histórico de chats em grupo está habilitado. Como alternativa por chat, use a permissão de consentimento específica do recurso ChatMember.Read.Chat.
2. Conceda consentimento do administrador para o locatário.
3. Obtenha o ID do seu site do SharePoint:
   # Via Graph Explorer ou curl com um token válido:
   curl -H "Authorization: Bearer $TOKEN" \
     "https://graph.microsoft.com/v1.0/sites/{hostname}:/{site-path}"
   
   # Exemplo: para um site em "contoso.sharepoint.com/sites/BotFiles"
   curl -H "Authorization: Bearer $TOKEN" \
     "https://graph.microsoft.com/v1.0/sites/contoso.sharepoint.com:/sites/BotFiles"
   
   # A resposta inclui: "id": "contoso.sharepoint.com,guid1,guid2"
   
4. Configure o OpenClaw:
   {
     channels: {
       msteams: {
         // ... outras configurações ...
         sharePointSiteId: "contoso.sharepoint.com,guid1,guid2",
       },
     },
   }
   

​

Comportamento de compartilhamento

​

Comportamento alternativo

​

Local de armazenamento dos arquivos

​

Enquetes (Cartões Adaptáveis)

• CLI: openclaw message poll --channel msteams --target conversation:<id> --poll-question "..." --poll-option "..." --poll-option "...".
• Os votos são registrados pelo Gateway no SQLite de estado do Plugin do OpenClaw em state/openclaw.sqlite.
• Os arquivos msteams-polls.json existentes são importados por openclaw doctor --fix, não pelo Plugin em execução.
• O Gateway deve permanecer online para registrar os votos.
• As enquetes não publicam automaticamente resumos dos resultados e ainda não há uma CLI de resultados de enquetes.

​

Cartões de apresentação

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

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

​

Formatos de destino

# Enviar para um usuário por ID
openclaw message send --channel msteams --target "user:40a1a0ed-..." --message "Olá"

# Enviar para um usuário pelo nome de exibição (aciona uma consulta à API Graph)
openclaw message send --channel msteams --target "user:John Smith" --message "Olá"

# Enviar para um chat em grupo ou canal
openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" --message "Olá"

# Enviar um cartão de apresentação para uma conversa
openclaw message send --channel msteams --target "conversation:19:abc...@thread.tacv2" \
  --presentation '{"title":"Olá","blocks":[{"type":"text","text":"Olá"}]}'

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

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

​

Mensagens proativas

• As mensagens proativas só são possíveis depois que um usuário interage, pois o OpenClaw armazena as referências da conversa nesse momento.
• Consulte /gateway/configuration para saber mais sobre dmPolicy e a restrição por lista de permissões.

​

IDs de equipe e canal (armadilha comum)

https://teams.microsoft.com/l/team/19%3ABk4j...%40thread.tacv2/conversations?groupId=...
                                    └────────────────────────────┘
                                    ID da conversa da equipe (decodifique a URL)

https://teams.microsoft.com/l/channel/19%3A15bc...%40thread.tacv2/ChannelName?groupId=...
                                      └─────────────────────────┘
                                      ID do canal (decodifique a URL)

• Chave da equipe = segmento do caminho após /team/ (com a URL decodificada, por exemplo, 19:Bk4j...@thread.tacv2; locatários mais antigos podem mostrar @thread.skype, que também é válido).
• Chave do canal = segmento do caminho após /channel/ (com a URL decodificada).
• Ignore o parâmetro de consulta groupId para o roteamento do OpenClaw. Ele é o ID do grupo do Microsoft Entra, não o ID da conversa do Bot Framework usado nas atividades recebidas do Teams.

​

Canais privados

1. Use canais padrão para interações com o bot.
2. Use mensagens diretas; os usuários sempre podem enviar mensagens diretamente ao bot.
3. Use a API Graph para acesso ao histórico (requer ChannelMessage.Read.All).

​

Solução de problemas

​

Problemas comuns

• Imagens não aparecem nos canais: faltam permissões do Graph ou consentimento do administrador. Reinstale o aplicativo do Teams, feche-o completamente e abra-o novamente.
• Sem respostas no canal: as menções são obrigatórias por padrão; defina channels.msteams.requireMention=false ou configure por equipe/canal.
• Incompatibilidade de versão (o Teams ainda mostra o manifesto antigo): remova e adicione novamente o aplicativo e feche completamente o Teams para atualizá-lo.
• 401 Unauthorized do webhook: esperado ao testar manualmente sem um JWT do Azure; significa que o endpoint está acessível, mas a autenticação falhou. Use o Azure Web Chat para testar corretamente.

​

Erros no upload do manifesto

• “Icon file cannot be empty”: o manifesto referencia arquivos de ícone com 0 bytes. Crie ícones PNG válidos (32x32 para outline.png, 192x192 para color.png).
• “webApplicationInfo.Id already in use”: o aplicativo ainda está instalado em outra equipe/chat. Primeiro, localize-o e desinstale-o ou aguarde 5-10 minutos pela propagação.
• “Something went wrong” durante o upload: faça o upload por https://admin.teams.microsoft.com, abra as Ferramentas do Desenvolvedor do navegador (F12) → guia Network e verifique o corpo da resposta para identificar o erro real.
• Falha no sideload: tente “Upload an app to your org’s app catalog” em vez de “Upload a custom app”; isso frequentemente contorna as restrições de sideload.

​

Permissões RSC não funcionam

1. Verifique se webApplicationInfo.id corresponde exatamente ao App ID do seu bot.
2. Faça novamente o upload do aplicativo e reinstale-o na equipe/chat.
3. Verifique se o administrador da sua organização bloqueou as permissões RSC.
4. Confirme se está usando o escopo correto: ChannelMessage.Read.Group para equipes, ChatMessage.Read.Chat para chats em grupo.

​

Referências

• Criar um Azure Bot - guia de configuração do Azure Bot
• Portal do Desenvolvedor do Teams - crie/gerencie aplicativos do Teams
• Esquema do manifesto de aplicativo do Teams
• Receber mensagens de canal com RSC
• Referência de permissões RSC
• Tratamento de arquivos por bots do Teams (canal/grupo requer o Graph)
• Mensagens proativas
• @microsoft/teams.cli - CLI do Teams para gerenciamento de bots

​

Relacionado

• Visão geral dos canais - todos os canais compatíveis
• Pareamento - autenticação por mensagem direta e fluxo de pareamento
• Grupos - comportamento do chat em grupo e controle por menções
• Roteamento de canais - roteamento de sessões para mensagens
• Segurança - modelo de acesso e reforço de segurança