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

{% 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**](#passo-01-registre-a-aplicacao-no-azure)[**:** Registre o novo aplicativo e gere as credenciais.](#passo-01-registre-a-aplicacao-no-azure)
* [**\[Passo 02\] Configure a Aplicação:** Configure e gere dados para os próximos passos.](#passo-02-configure-a-aplicacao)
* [**\[Passo 03\] Crie um Fluxo do Agente:** Crie um fluxo do agente para interagir com o bot.](#passo-03-crie-um-fluxo-do-agente)
* [**\[Passo 04\] Crie a publicação no Studio:** Crie uma nova Publicação do tipo Microsoft Teams no Studio.](#passo-04-crie-uma-publicacao-com-o-microsoft-teams-no-studio)
* [**\[Passo 05\] Configure a URL de Webhook na Azure:** Defina a URL de Webhook no fluxo de autenticação.](#passo-05-configure-a-url-de-webhook-na-azure)
* [**\[Passo 06\] Configure as permissões de API:** Defina os escopos de acesso do Microsoft Graph.](#passo-06-configure-as-permissoes-de-api)
* [**\[Passo 07\] Crie o Azure Bot:** Estabeleça o recurso de serviço do bot no Azure.](#passo-07-crie-o-azure-bot)
* [**\[Passo 08\] Configure o Azure Bot:** Vincule o bot à URL de mensagens do Studio.](#passo-08-configure-o-azure-bot)
* [**\[Passo 09\] Habilite o canal Microsoft Teams:** Ative a comunicação específica para o Teams.](#passo-09-habilite-o-canal-microsoft-teams)
* [**\[Passo 10\] Prepare o Manifesto:** Crie o pacote de instalação do aplicativo.](#passo-10-prepare-o-manifesto)
* [**\[Passo 11 Realize o Upload:** Publique o bot no ambiente organizacional.](#passo-11-realize-o-upload)
* [**\[Passo 12\] Valide a integração:** Teste a comunicação final entre as pontas.](#passo-12-valide-a-integracao)

***

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

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

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

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


```

{% 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 11: 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 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

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.skyone.cloud/skyone-studio/inteligencia-artificial/agentes/canais-de-publicacao-de-agentes-de-ia/como-configurar-o-microsoft-teams-no-skyone-studio.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.