How to set up Microsoft Teams in Skyone Studio

Esta documentação descreve o processo completo para configurar a integração do Microsoft Teams no Skyone Studio. O objetivo é permitir que agentes inteligentes criados no Skyone Studio se comuniquem diretamente com usuários através de chats e canais no no ambiente Microsoft (Azure e Teams).

Benefícios:

• Centraliza a comunicação com agentes de IA dentro do ambiente corporativo do Teams.

• Permite o envio de mensagens proativas e automação de respostas.

• Garante uma integração segura utilizando os protocolos de autenticação da Microsoft.

Pré-requisitos e permissões:

1. Permissões Administrativas e de Sistema:

• Permissões administrativas no Azure.

• Perfil de Microsoft Teams Administrator.

• Permissão AI Admin no Azure (para gerenciar Grupos de Recursos).

• Permissão Azure Bot Service Contributor Role (obrigatória para a criação do Bot).

• Acesso ao serviço Bot Framework / Bot Service / Azure Bot.

2. Permissões do Microsoft Graph (Configuradas no Azure):

Durante o registro da aplicação no Azure, você deve fornecer as seguintes permissões:

• AppCatalog.ReadWrite.All: Permite publicar o bot no catálogo de aplicativos do Microsoft Teams.

• TeamsAppInstallation.ReadWriteSelfForUser.All: Permite a instalação do bot para usuários específicos.

• Chat.ReadWrite.All: Garante ao bot o envio e recebimento de mensagens proativas em chats e canais.

• User.Read.All: Permite a leitura de informações de perfis e logs de uso do bot.

3. Configurações no Teams Admin Center:

É necessário permitir o upload de aplicativos customizados (sideload) seguindo este caminho:

• Acesse Teams Admin Center → Teams apps → Setup policies.

• Habilite a opção Upload custom apps.

• Certifique-se de que o menu Aplicativos esteja visível habilitando a opção Show app bar.

Observações Importantes:

• Contas: Utilize obrigatoriamente uma conta corporativa com domínio .com.br. Domínios customizados ou contas pessoais não são aceitos e podem impedir a validação do bot.

• Provedores Azure: O provedor de recurso Microsoft.BotService deve estar habilitado na assinatura Azure utilizada para evitar falhas na criação do bot.

---

Etapas de configuração

Para configurar o Microsoft Teams, você precisará alternar entre o Portal Azure, o Teams Admin Center e o Skyone Studio.

Passos:

• [Passo 01] Registre a aplicação no Azure: Crie a base de autenticação e gere as credenciais.

• [Passo 02] Configure a aplicação: Defina as URLs de redirecionamento necessárias para o OAuth.

• [Passo 03] Crie o Secret: Gere a chave secreta para autenticação entre plataformas.

• [Passo 04] Configure as permissões de API: Defina os escopos de acesso do Microsoft Graph.

• [Passo 05] Crie o Azure Bot: Estabeleça o recurso de serviço do bot no Azure.

• [Passo 06] Configure o Azure Bot: Vincule o bot à URL de mensagens do Studio.

• [Passo 07] Habilite o canal Microsoft Teams: Ative a comunicação específica para o Teams.

• [Passo 08] Configure a conta no Skyone Studio: Cadastre as credenciais e gere o webhook.

• [Passo 09] Prepare o Manifesto: Crie o pacote de instalação do aplicativo.

• [Passo 10] Realize o Upload: Publique o bot no ambiente organizacional.

• [Passo 11] Valide a integração: Teste a comunicação final entre as pontas.

---

Passo 01: Registre a aplicação no Azure

1. Acesse o Portal Azure e vá em Registros de Aplicativo > Novo Registro.

2. No campo Nome, digite uma identificação (ex: Microsoft_Teams_Integration).

3. Em Tipos de conta com suporte, selecione Contas somente neste diretório organizacional (Single Tenant).

4. Em ULR de redirecionamento, selecione Plataforma Web e insira a URL do Webhook (obtido no Skyone Studio).

5. Clique em Registrar.

Copie imediatamente o Valor do segredo, pois ele será exibido apenas uma vez e será necessário no Skyone Studio.

Passo 02: Configure a Aplicação

1. Ainda no Portal Azure e vá em Registros de Aplicativo > Aplicativos com Propriedade.

2. Acesse Gerenciar > Authentication (Preview)

3. Em ULR de redirecionamento, selecione Plataforma Web e insira a URL do Webhook.

Algumas requisições do OAuth exigem que o redirect esteja explicitamente configurado.

Passo 3: Crie o Secret

1. Ainda no Portal Azure e vá em Certificados e Segredos > Novo segredo do cliente.

2. Defina uma descrição e o tempo de expiração (no máximo 6 meses).

Copie imediatamente o Valor do segredo, pois ele será exibido apenas uma vez e será necessário no Skyone Studio.

Passo 04: Configure as permissões de API

1. No menu lateral da aplicação criada, acesse Permissões de API > Adicionar uma permissão.

2. Selecione Microsoft Graph e adicione as seguintes permissões de aplicativo:

   • AppCatalog.ReadWrite.All.

   • Chat.ReadWrite.All.

   • TeamsAppInstallation.ReadWriteSelfForUser.All.

   • User.Read.All.

3. Clique em Conceder consentimento do administrador para ativar as permissões ou aguarde a aprovação de um administrador.

Passo 05: Crie o Azure Bot

1. No Portal Azure, acesse Bot Services

2. Clique em Criar e, em seguida, Azure Bot.

3. Preencha os campos conforme a tabela abaixo:

• Bot handle: Ex.: teams-integration-bot.

• Data residency: Global.

• Pricing: Standard.

• Microsoft App ID: Single Tenant.

• Creation type: Use existing app registration.

• App ID: O Client ID da aplicação criada no Passo 03.

• App tenant ID: O Tenant ID da aplicação criada no Passo 03.

4. Clique em Criar para finalizar.

Passo 06: Configure o Azure Bot

1. Acesse o bot criado.

2. Acesse Configuração.

3. No campo Ponto de extremidade de mensagens, cole a URL de Webhook gerada no Studio.

4. Clique em Salvar.

Passo 07: Habilite o canal Microsoft Teams

Para habilitar o bot especificamente para o Teams:

1. Vá em Canais.

2. Em Messaging escolha Microsoft Teams Commercial

3. Clique em Apply.

Passo 08: Configure a conta no Skyone Studio

1. Acesse o Skyone Studio e abra o Fluxo do Agente desejado.

2. Clique em Publicar e selecione a opção Microsoft Teams.

3. Clique em Gerenciar contas e depois em Criar conta.

4. Preencha os campos com as informações obtidas no Azure:

   • Nome: Identificação da conta no Studio.

   • Client ID: ID do aplicativo.

   • Tenant ID: ID do diretório.

   • Client Secret: O valor do segredo gerado anteriormente.

5. Clique em Criar. O sistema gerará automaticamente uma URL de Webhook.

6. Copie esta URL, volte ao Portal Azure no seu Azure Bot, acesse Configuração e cole-a no campo Ponto de extremidade de mensagens.

Passo 09: Prepare o Manifesto

O Sideload permite testar o bot internamente antes da publicação oficial para toda a organização.

• Sideload = teste local/individual

• Publicação no catálogo = teste oficial/organizacional

1. Crie um arquivo chamado manifest.json utilizando o modelo padrão da Microsoft, inserindo o seu Client ID nos campos id e botId.

{
  "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.17/MicrosoftTeams.schema.json",
  "manifestVersion": "1.16",
  "version": "1.0.0",
  "id": "[Seu Client ID do Azure AD]",
  "developer": {
    "name": "[Nome exemplo]",
    "websiteUrl": "https://www.exemplo.com/",
    "privacyUrl": "https://www.exemplo.com/politica-de-privacidade/",
    "termsOfUseUrl": "https://www.exemplo.com/termos-de-uso/"
  },
  "name": {
    "short": "[Nome Curto do Seu Bot]",
    "full": "[Nome Completo do Seu Bot]"
  },
  "description": {
    "short": "[Descrição Curta]",
    "full": "[Descrição Completa]"
  },
  "icons": {
    "outline": "outline.png",
    "color": "color.png"
  },
  "accentColor": "#FFFFFF",
  "bots": [
    {
      "botId": "[Seu Client ID do Azure AD]",
      "scopes": ["personal", "team", "groupChat"],
      "supportsFiles": false,
      "isNotificationOnly": false
    }
  ],
  "composeExtensions": [],
  "permissions": [
    "identity",
    "messageTeamMembers"
  ],
  "validDomains": [
    "[Domínio do Webhook]"
  ]
}

Cada upload exige incremento de versão.

O arquivo manifest.json define como o aplicativo será exibido no Microsoft Teams e quais permissões ele utilizará.

1. Prepare duas imagens de ícone: color.png ($192\times192$ px) e outline.png ($32\times32$ px).

2. Selecione os três arquivos (manifest.json, color.png e outline.png) e compacte-os em um arquivo .zip.

Comprima os arquivos diretamente, e não a pasta onde eles estão, para evitar erros de leitura.

Passo 10: Realize o Upload

1. Como administrador, acesse o Teams Admin Center da Micrososft.

2. No menu lateral esquerdo, acesse Teams apps > Setup policies

3. Selecione a política Global (Org-wide Default).

4. Ative a opção Upload custom apps

Sem esta ativação, não será possível carregar aplicativos externos no ambiente.

1. Faça login no Microsoft Teams (Web ou Desktop) utilizando seu usuário do Azure que possua uma licença ativa.

2. Clique no ícone Aplicativos, localizado no menu lateral esquerdo.

3. Selecione a opção Gerenciar Seus Aplicativos.

4. Clique em Carregar Um Aplicativo e, em seguida, em Fazer O Upload De Um Aplicativo Personalizado.

5. Selecione o arquivo .zip criado anteriormente (contendo o manifest.json e as imagens).

6. Confirme as informações exibidas na tela inicial e clique em Adicionar.

Passo 11: Valide a integração

1. Abra o chat com o bot recém-adicionado e envie uma mensagem de saudação, como "Olá".

2. Confirme se a mensagem foi recebida corretamente pelo fluxo configurado no Skyone Studio através do webhook cadastrado.

O recebimento da resposta confirma que a integração entre o Microsoft Teams e o Skyone Studio foi concluída com sucesso.

---

FAQ - Integração Microsoft Teams

Posso usar uma conta pessoal para configurar o Teams?

Não. É necessário utilizar uma conta corporativa com domínio (ex: .com.br) vinculada ao ambiente organizacional.

Por que meu upload de aplicativo personalizado falhou?

Verifique se a opção Upload custom apps está habilitada no Teams Admin Center em Setup policies. Certifique-se também de que compactou apenas os arquivos, e não a pasta.

O que fazer se o bot não responder no Teams?

Confira se a URL de Webhook gerada no Skyone Studio foi colada corretamente no campo Messaging endpoint do Azure Bot. Verifique também se as permissões de API no Azure receberam o consentimento do administrador.