Cómo configurar Microsoft Teams en Skyone Studio?

Esta documentación describe el proceso completo para configurar la integración de Microsoft Teams en Skyone Studio. El objetivo es permitir que agentes inteligentes creados en Skyone Studio se comuniquen directamente con usuarios a través de chats y canales en el entorno Microsoft (Azure y Teams).

Beneficios:

• Centraliza la comunicación con agentes de IA dentro del entorno corporativo de Teams.

• Permite el envío de mensajes proactivos y automatización de respuestas.

• Garantiza una integración segura utilizando los protocolos de autenticación de Microsoft.

Prerrequisitos y permisos:

1. Permisos Administrativos y de Sistema:

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

• Permisos administrativos en Azure.

• Perfil de Microsoft Teams Administrator.

• Permiso AI Admin en Azure (para gestionar Grupos de Recursos).

• Permiso Azure Bot Service Contributor Role (obligatorio para la creación del Bot).

• Acceso al servicio Bot Framework / Bot Service / Azure Bot.

2. Permisos de Microsoft Graph (Configurados en Azure):

Durante el registro de la aplicación en Azure, debe proporcionar los siguientes permisos:

• AppCatalog.ReadWrite.All: Permite publicar el bot en el catálogo de aplicaciones de Microsoft Teams.

• TeamsAppInstallation.ReadWriteSelfForUser.All: Permite la instalación del bot para usuarios específicos.

• Chat.ReadWrite.All: Garantiza al bot el envío y recepción de mensajes proactivos en chats y canales.

• User.Read.All: Permite la lectura de información de perfiles y logs de uso del bot.

3. Configuraciones en Teams Admin Center:

Es necesario permitir la carga de aplicaciones personalizadas (sideload) siguiendo esta ruta:

• Acceda a Teams Admin Center → Teams apps → Setup policies.

• Habilite la opción Upload custom apps.

• segúrese de que el menú Aplicaciones esté visible habilitando la opción Show app bar.

Observaciones importantes:

• Cuentas: Utilice obligatoriamente una cuenta corporativa con dominio .com.br. No se aceptan dominios personalizados o cuentas personales y pueden impedir la validación del bot.

• Proveedores Azure: El proveedor de recursos Microsoft.BotService debe estar habilitado en la suscripción Azure utilizada para evitar fallas en la creación del bot.

---

Etapas de configuración

Para configurar o Microsoft Teams, deberá alternar entre el Portal Azure, el Teams Admin Center y Skyone Studio.

Pasos:

• [Paso 01] Registre la aplicación en Azure: Registre la nueva aplicación y genere las credenciales.

• [Paso 02] Configure la Aplicación: Configure y genere datos para los próximos pasos.

• [Paso 03] Cree un Flujo del Agente: Cree un flujo para interactuar con el bot.

• [Paso 04] Cree la publicación en Studio: Cree una nueva publicación de tipo Microsoft Teams.

• [Paso 05] Configure la URL de Webhook en Azure: Defina la URL en el flujo de autenticación.

• [Paso 06] Configure los permisos de API: Defina los alcances de acceso de Microsoft Graph.

• [Paso 07] Cree el Azure Bot: Establezca el recurso de servicio del bot en Azure.

• [Paso 08] Configure el Azure Bot: Vincule el bot a la URL de mensajes de Studio.

• [Paso 09] Habilite el canal Microsoft Teams: Active la comunicación específica para Teams.

• [Paso 10] Prepare el Manifiesto: Cree el paquete de instalación de la aplicación.

• [Paso 11] Realice la carga: Publique el bot en el entorno organizacional.

• [Paso 12] Valide la integración: Pruebe la comunicación final entre los puntos.

---

Paso 01: Registre la aplicación en Azure

1. Acceda al Portal Azure y vaya a Registros de aplicaciones > Nuevo registro.

2. En el campo Nombre, escriba una identificación (ej: Microsoft_Teams_Integration).

3. En Tipos de cuenta compatibles, seleccione Solo cuentas de este directorio organizacional (Single Tenant).

4. Haga clic en Registrar.

Paso 02: Configure la Aplicación

1. En el Portal Azure, vaya a Registros de aplicaciones > Aplicaciones que son propiedad.

2. Vaya a Certificados y secretos > Nuevo secreto de cliente.

3. Defina una descripción y el tiempo de expiración (máximo 6 meses).

Importante: Copie inmediatamente el Valor del secreto, ya que se mostrará solo una vez y será necesario en Skyone Studio.

Guarde el ID de la aplicación (cliente) y el ID del directorio (inquilino).

Paso 03: Cree un Flujo del Agente

1. En Skyone Studio vaya a Flujo del Agente.

2. Haga clic en Crear flujo.

3. Agregue los componentes según sea necesario, asegurándose de tener un agente configurado en el flujo.

Paso 04: Cree una publicación con Microsoft Teams no Studio

1. En Skyone Studio, vaya a Flujo del Agente.

2. Haga clic en Publicar.

3. Haga clic en Microsoft Teams.

4. Seleccione un Flujo de Agente creado previamente.

5. Haga clic en Gestionar Cuentas.

6. Haga clic en Crear Cuenta.

7. Ingrese los datos:

   1. Nombre: Nombre de la cuenta

   2. Client ID: ID de la aplicación (cliente)

   3. Client Secret: Secreto generado en el paso 2

   4. Tenant ID: ID de directorio (inquilino)

8. Haga clic en Crear.

9. Haga clic en Guardar Publicación.

10. Copia y guarda la URL del webhook generada.

Paso 05: Configure la URL de Webhook en Azure

1. En el Portal Azure, vaya a Registros de Aplicativo > Aplicativos com Propriedade.

2. Accede Gestión → Authentication (Preview).

3. Añade la URL de redirecionamento:

   1. Plataforma Web

   2. Pega la URL del Webhook obtenida de Skyone Studio

Paso 06: Configure los permisos de API

1. En el menú lateral de la aplicación creada, vaya a Permisos de API > Agregar un permiso.

2. Seleccione Microsoft Graph y agregue los siguientes permisos de la aplicación:

   • AppCatalog.ReadWrite.All.

   • Chat.ReadWrite.All.

   • TeamsAppInstallation.ReadWriteSelfForUser.All.

   • User.Read.All.

3. Haz clic en Otorgar consentimiento al administrador para habilitar los permisos o espera la aprobación del administrador.

Paso 07: Cree el Azure Bot

1. En Portal Azure, acceda Bot Services

2. Haz clic en Crear > Azure Bot.

3. Rellene los campos según la tabla que aparece a continuación:

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

• Data residency: Global.

• Pricing: Standard.

• Microsoft App ID: Single Tenant.

• Creation type: Use existing app registration.

• App ID: El ID de la aplicación (cliente) creada en el paso 2.

• App tenant ID: El ID del directorio (inquilino) creado en el paso 2.

4. Haga clic en Crear para finalizar.

Paso 08: Configure el Azure Bot

1. Acceda al bot creado.

2. Acceda a Configuración.

3. En el campo Punto de conexión de mensajería, pegue la URL de Webhook generada en Skyone Studio (Paso 04).

4. Haga clic en Guardar.

Paso 09: Habilite el canal Microsoft Teams

Para habilitar el bot específicamente para el Teams:

1. Vaya a Canales.

2. En Messaging, escoja Microsoft Teams Commercial

3. Haga clic en Apply.

Paso 10: Prepare el Manifiesto

El Sideload permite probar el bot internamente antes de la publicación oficial para toda la organización.

• Sideload = prueba local/individual.

• Publicación en el catálogo = prueba oficial/organizacional.

1. Cree un archivo llamado manifest.json utilizando el modelo estándar de Microsoft, insertando su Client ID en los campos id y 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 de la Aplicación(cliente)]",
  "developer": {
    "name": "[Nombre de la empresa]",
    "websiteUrl": "[Website URL]",
    "privacyUrl": "https://termly.io/es/recursos/articulos/que-es-una-politica-de-privacidad/",
    "termsOfUseUrl": "https://es.wikipedia.org/wiki/T%C3%A9rminos_y_condiciones_de_uso"
  },
  "name": {
    "short": "[Nombre del Bot - Corto]",
    "full": "[Nombre del Bot - Completo]"
  },
  "description": {
    "short": "[Descripción - Corta]",
    "full": "[Descripción - Completa]"
  },
  "icons": {
    "outline": "outline.jpg",
    "color": "color.jpg"
  },
  "accentColor": "#FFFFFF",
  "bots": [
    {
      "botId": "[ID de la Aplicación(cliente)]",
      "scopes": ["personal", "team", "groupChat"],
      "supportsFiles": true,
      "isNotificationOnly": false
    }
  ],
  "composeExtensions": [],
  "permissions": [
    "identity",
    "messageTeamMembers"
  ],
  "validDomains": [
    "https://www.dondominio.com/es/products/domains/studio/"
  ]
}": "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 versión.

El archivo manifest.json define cómo el aplicativo será exhibido en Microsoft Teams y qué permisos utilizará.

1. Prepare dos imágenes de icono: color.png (192x192 px) y outline.png (32x32 px).

2. Seleccione los tres archivos (manifest.json, color.png y outline.png) y compacte los mismos en un archivo .zip.

Comprima los archivos directamente, y no la carpeta donde están, para evitar errores de lectura.

Paso 11: Realice el Upload

1. Como administrador, acceda al Teams Admin Center de Micrososft.

2. En el menú lateral izquierdo, acceda a Teams apps > Setup policies

3. Seleccione la política Global (Org-wide Default).

4. Active la opción Upload custom apps

Sin esta activación, no será posible cargar aplicativos externos en el ambiente.

1. Inicie sesión en Microsoft Teams (Web o Desktop) utilizando su usuario de Azure que posea una licencia activa.

2. Haga clic en el icono Aplicaciones, localizado en el menú lateral izquierdo.

3. Seleccione la opción Gestionar Sus Aplicaciones.

4. Haga clic en Cargar Un Aplicativo y, en seguida, en Realizar El Upload De Un Aplicativo Personalizado.

5. Seleccione el archivo .zip creado anteriormente (conteniendo el manifest.json y las imágenes).

6. Confirme las informaciones exhibidas en la pantalla inicial y haga clic en Añadir.

Paso 12: Valide la integración

1. Abra el chat con el bot recién añadido y envíe una mensaje de saludo, como "Hola".

2. Confirme si el mensaje fue recibido correctamente por el flujo configurado en Skyone Studio a través del webhook registrado.

El recibimiento de la respuesta confirma que la integración entre el Microsoft Teams y el Skyone Studio se ha completado con éxito.

---

FAQ - Integración Microsoft Teams

¿Puedo usar una cuenta personal para configurar Teams?

No. Necesitas usar una cuenta corporativa con un dominio (p. ej., .com.br) vinculado al entorno de la organización.

¿Por qué falló la carga de mi aplicación personalizada?

Verifica que la opción "Cargar aplicaciones personalizadas" esté habilitada en el Centro de administración de Teams, en la sección de Directivas de configuración. Además, asegúrate de haber comprimido solo los archivos, no la carpeta.

¿Qué hacer si el bot no responde en Teams?

Verifica que la URL del webhook generada en Skyone Studio se haya pegado correctamente en el campo "Punto de conexión de mensajería" del bot de Azure. Asimismo, verifica que los permisos de la API en Azure cuenten con el consentimiento del administrador.