Skip to main content
Acessar Studio

Microsoft Teams

A integração com o Microsoft Teams permite que o agente responda a mensagens diretamente no chat da sua organização, através de um bot registrado no Azure / Bot Framework.

Acesse pelo ícone Configurações → aba Integrações → card Microsoft Teams.

Habilitar a integração​

Ative o toggle no card do Microsoft Teams. Os campos de configuração ficam visíveis após a ativação.

Como funciona​

  1. O Teams envia uma activity (mensagem, entrada em conversa, anexo, etc.) para o endpoint público do Roberty.
  2. O Roberty valida o JWT emitido pelo Bot Framework (aud = appId do bot).
  3. O agente correspondente ao tenantId do payload é resolvido e executado.
  4. A resposta é enviada de volta ao Teams pela API serviceUrl do próprio Bot Framework, autenticada com OAuth2 client_credentials.

O Roberty mantém o histórico de cada conversa (por conversationId), respeitando a configuração de Memória do agente, para que ele tenha contexto entre as mensagens.

Campos de configuração​

CampoDescrição
Tenant IDID do tenant do Azure Active Directory (formato UUID)
App ID (Bot)Application (client) ID do App Registration criado no portal Azure
App PasswordClient secret do aplicativo registrado no Azure
Mensagem de boas-vindasMensagem exibida quando o usuário inicia uma conversa no Teams (opcional)

Pré-requisitos​

  • Um App Registration e um Azure Bot (Azure Bot Service).
  • Do App Registration você precisará de:
    • Application (client) ID → appId
    • Client secret → appPassword
    • Directory (tenant) ID → tenantId
Ponto crítico — o bot é single-tenant

O bot só autentica no seu próprio tenant, então o App Registration precisa existir no mesmo tenant do Teams onde o bot será usado. Se a sua conta do Azure fica em um tenant diferente do Microsoft 365/Teams, crie o App Registration no tenant do Teams (App registrations é do Entra ID e não exige assinatura do Azure). O recurso Azure Bot pode ficar na sua assinatura, apontando para esse app.

Configurando o bot no Azure​

1. Criar o App Registration (no tenant do Teams)​

  1. No portal.azure.com, troque o diretório para o tenant do Teams.
  2. Microsoft Entra ID → App registrations → New registration.
  3. Em Supported account types, escolha Accounts in this organizational directory only (single-tenant).
  4. Anote o Application (client) ID e o Directory (tenant) ID.
  5. Em Certificates & secrets → New client secret, gere e copie o value (exibido só uma vez).

2. Criar o Azure Bot​

  1. Create a resource → Azure Bot, tipo Single Tenant, opção Use existing app registration.
  2. Informe o App ID e o App tenant ID (o Directory ID do passo anterior).
  3. Em Configuration → Messaging endpoint, informe:
https://agent-backend.roberty.app/integrations/teams
  1. Em Channels, adicione o canal Microsoft Teams.
info

O Roberty usa uma única rota para Teams e resolve o agente pelo tenantId que vem no payload.

3. Configurar o agente no Roberty​

Preencha nesta tela os campos Tenant ID, App ID, App Password e, opcionalmente, a Mensagem de boas-vindas.

4. Baixar o manifesto e publicar no Teams​

Use o botão Baixar manifesto (.zip), disponível no card do Teams — ele gera um pacote pronto (manifest.json + ícones) usando o nome e a descrição do agente e o App ID informado. O botão fica disponível quando há um App ID preenchido e uma versão publicada do agente.

No cliente do Teams: Apps → Manage your apps → Upload an app → Upload a custom app e selecione o .zip gerado. (O upload de apps personalizados precisa estar habilitado no admin do Teams.)

Recursos​

  • Memória de conversa: o histórico é mantido por conversa e limitado pela janela definida em Memória do agente.
  • Encerrar conversa: o usuário pode enviar /reset (ou /novaconversa, /encerrar, /limpar, /clear, /new) para finalizar — o agente gera uma mensagem de encerramento e o histórico é apagado.
  • Anexos: arquivos enviados no chat têm o texto extraído e entregue ao agente. Documentos (PDF, DOCX, etc.) funcionam de forma nativa; imagens dependem de OCR.

Validação de segurança​

O Roberty valida todo request:

  • O header Authorization: Bearer <jwt> é verificado contra as chaves públicas em https://login.botframework.com/v1/.well-known/keys.
  • A audiência do token precisa ser igual ao appId configurado no agente.
  • O emissor precisa ser https://api.botframework.com ou https://sts.windows.net/<tenantId>/.

Requests sem token ou com token inválido retornam 401.

Resolução de problemas​

SintomaCausa provável
AADSTS700016: Application ... was not found in the directoryO App Registration não está no tenant usado para autenticar — o app precisa existir no tenant do Teams (tenantId).
401 Invalid tokenappId configurado no agente não bate com o do App Registration.
404 Agent not configured for tenanttenantId no agente não bate com o da organização que enviou a mensagem.
Bot fica "digitando" e nunca respondeappPassword incorreto ou expirado; verifique o secret.
Mensagem de boas-vindas não apareceEvento conversationUpdate não chegou, ou welcomeMessage em branco.
Manifesto não valida no uploadO App ID informado não é um GUID válido, ou falta uma versão publicada do agente.

Referências​