# 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**.

{% hint style="warning" %}
**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.
  {% endhint %}

***

#### 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**.

{% hint style="warning" %}
Copie imediatamente o Valor do segredo, pois ele será exibido apenas uma vez e será necessário no **Skyone Studio**.
{% endhint %}

#### 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.

{% hint style="warning" %}
Algumas requisições do OAuth exigem que o redirect esteja explicitamente configurado.
{% endhint %}

#### 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).

{% hint style="warning" %}
Copie imediatamente o Valor do segredo, pois ele será exibido apenas uma vez e será necessário no Skyone Studio.
{% endhint %}

#### 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.

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

```

{% hint style="warning" %}
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á.
{% endhint %}

2. Prepare duas imagens de ícone: **color.png** ($192\times192$ px) e **outline.png** ($32\times32$ px).
3. Selecione os três arquivos (manifest.json, color.png e outline.png) e compacte-os em um arquivo .zip.

{% hint style="danger" %}
Comprima os arquivos diretamente, e não a pasta onde eles estão, para evitar erros de leitura.
{% endhint %}

####  Passo 10: Realize o Upload

1. Como administrador, acesse o [Teams Admin Center](https://admin.teams.microsoft.com) 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** 

{% hint style="warning" %}
Sem esta ativação, não será possível carregar aplicativos externos no ambiente.
{% endhint %}

5. [Faça login](https://www.microsoft.com/en-us/microsoft-teams/log-in) no Microsoft Teams (Web ou Desktop) utilizando seu usuário do Azure que possua uma licença ativa.
6. Clique no ícone **Aplicativos**, localizado no menu lateral esquerdo.
7. Selecione a opção **Gerenciar Seus Aplicativos**.
8. Clique em **Carregar Um Aplicativo** e, em seguida, em **Fazer O Upload De Um Aplicativo Personalizado.**
9. Selecione o arquivo .zip criado anteriormente (contendo o manifest.json e as imagens).
10. 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

<details>

<summary>Posso usar uma conta pessoal para configurar o Teams?</summary>

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

</details>

<details>

<summary>Por que meu upload de aplicativo personalizado falhou? </summary>

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.

</details>

<details>

<summary>O que fazer se o bot não responder no Teams? </summary>

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.

</details>