Como configurar o Microsoft Teams no 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: Registre o novo aplicativo e gere as credenciais.

• [Passo 02] Configure a Aplicação: Configure e gere dados para os próximos passos.

• [Passo 03] Crie um Fluxo do Agente: Crie um fluxo do agente para interagir com o bot.

• [Passo 04] Crie a publicação no Studio: Crie uma nova Publicação do tipo Microsoft Teams no Studio.

• [Passo 05] Configure a URL de Webhook na Azure: Defina a URL de Webhook no fluxo de autenticação.

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

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

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

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

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

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

• [Passo 12] 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. Clique em Registrar.

Passo 02: Configure a Aplicação

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

2. Vá em Certificados e Segredos > Novo segredo do cliente.

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

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

Copie e salve o ID do Aplicativo (Cliente) e o ID do diretório (Locatário), utilizaremos no próximo passo.

Passo 03: Crie um Fluxo do Agente

1. Acesse o Skyone Studio e vá em Fluxo do Agente.

2. Clique em Criar fluxo.

3. Adicione os componentes conforme a necessidade, certifique-se de que tenha um agente configurado no fluxo.

Passo 04: Crie uma publicação com o Microsoft Teams no Studio

1. Acesse o Skyone Studio e vá em Fluxo do Agente.

2. Clique em Publicar no canto superior direito.

3. Clique em Microsoft Teams.

4. Selecione um Fluxo do Agente previamente criado.

5. Clique em Gerenciar Contas.

6. Clique em Criar Conta.

7. Informe os seguintes dados:

   1. Nome: Nome da conta

   2. Client ID: ID do aplicativo (cliente)

   3. Client Secret: Segredo gerado no passo 2

   4. Tenant ID: ID do diretório (Locatário)

8. Clique em Criar.

9. Clique em Salvar Publicação.

10. Copie e salve a Webhook URL gerada

Passo 05: Configure a URL de Webhook na Azure

1. No Portal Azure, vá em Registros de Aplicativo > Aplicativos com Propriedade.

2. Acesse Gerenciar → Authentication (Preview).

3. Adicione a URI de redirecionamento:

   1. Plataforma Web

   2. Cole a URL do Webhook coletada do Skyone Studio

Passo 06: 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 07: 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 ID do Aplicativo(Cliente) da aplicação criada no Passo 02.

• App tenant ID: O ID do Diretório(locatário) da aplicação criada no Passo 02.

4. Clique em Criar para finalizar.

Passo 08: 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 Skyone Studio (Passo 04).

4. Clique em Salvar.

Passo 09: 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 10: 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.17",
  "version": "1.0.1",
  "id": [ID do Aplicativo(cliente)],
  "developer": {
    "name": "[Nome da empresa]",
    "websiteUrl": "[Website URL]",
    "privacyUrl": "[URL da Politicas de Privacidade]",
    "termsOfUseUrl": "[URL do Termos de Uso]"
  },
  "name": {
    "short": "[Nome do Bot - Curto]",
    "full": "[Nome do Bot - Completo]"
  },
  "description": {
    "short": "[Descricao - Curta]",
    "full": "[Descricao - Completa]"
  },
  "icons": {
    "outline": "outline.jpg",
    "color": "color.jpg"
  },
  "accentColor": "#FFFFFF",
  "bots": [
    {
      "botId": "[ID do Aplicativo(cliente)]",
      "scopes": ["personal", "team", "groupChat"],
      "supportsFiles": true,
      "isNotificationOnly": false
    }
  ],
  "composeExtensions": [],
  "permissions": [
    "identity",
    "messageTeamMembers"
  ],
  "validDomains": [
    "[URL do dominio do Studio]"
  ]
}

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 11: 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 12: 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.