Microsoft Teams

Resumen

El proveedor de Microsoft Teams integra tu trabajador digital con canales y chats de Teams. Admite:

• Mensajes de canal
• Chats personales
• Chats grupales
• Adaptive Cards
• Componentes interactivos
• Adjuntos de archivos

Requisitos previos

• Tenant de Microsoft 365
• Id de cliente de una aplicación pública de Microsoft Entra que admita OAuth con código de dispositivo
• Permiso para conceder o consentir los scopes de Graph usados por la configuración
• Permiso para crear canales en el Team seleccionado cuando quieras que la configuración cree un canal deseado que falte

Configuración

La configuración de Teams admite dos formas de configuración:

Modo	Úsalo cuando	Campos principales
Modo de canal de Graph	Quieres envíos y suscripciones de canal basados en Graph. Este es el modo de configuración predeterminado.	tenant_id, client_id, team_id, team_name, channel_id, channel_name, desired_channel_name
Modo Bot Framework	Tienes un Azure Bot y un manifiesto de app de Teams para mensajes entrantes de Bot Framework.	ms_bot_app_id, ms_bot_app_password, bot_display_name, messaging_endpoint

1. Configura la pista de configuración

   Puedes ejecutar la configuración solo con el id de cliente público predeterminado, o proporcionar tu propio client_id. Agrega desired_channel_name cuando quieras que la configuración busque o cree un canal estándar específico:

   answers.json

   {
     "setup_answers": {
       "messaging-teams": {
         "client_id": "6c115a7a-f656-49c4-975a-5e831efae833",
         "desired_channel_name": "hr onboarding"
       }
     }
   }

2. Inicia la configuración de Teams

   gtc setup --answers answers.json ./my-bundle

3. Completa OAuth con código de dispositivo

   La configuración inicia un flujo de código de dispositivo de Microsoft. Copia el código, abre la URL de verificación, inicia sesión con la cuenta de Microsoft 365 que puede acceder al Team objetivo y aprueba los scopes de Graph solicitados.

   Vuelve al terminal y continúa cuando la configuración te pida verificar la configuración de Microsoft Teams. Luego Greentic consulta Microsoft Graph, almacena los tokens delegados como secretos y ejecuta el descubrimiento posterior al inicio de sesión.

4. Selecciona o verifica el Team y el canal

   La configuración llama a Microsoft Graph para listar los equipos y canales a los que pertenece el usuario que inició sesión. Elige el Team y el canal cuando se te solicite, o deja que desired_channel_name guíe el flujo de crear si falta.

   La configuración guarda tanto los identificadores como las etiquetas:

   • team_id y team_name
   • channel_id y channel_name

   Los IDs son lo que usan los envíos de runtime y la configuración de suscripciones. Los nombres visibles son para operadores y UIs de configuración.

5. Comprueba el canal en Teams

   Abre Microsoft Teams y ve al Team y canal seleccionados. Si la configuración creó desired_channel_name, confirma que el canal existe y que la cuenta con sesión iniciada tiene acceso a él.

   Si el Team seleccionado aún no tiene ese canal, la configuración puede crear un canal estándar y luego guarda el channel_id y el channel_name resultantes. El ID sigue siendo la referencia autoritativa para envíos de runtime y suscripciones.

6. Inicia o reinicia el runtime

   gtc start ./my-bundle

   El pack de Teams declara los metadatos de suscripción deseados, incluida la plantilla de recurso de Graph, los campos de configuración del componente, la plantilla de URL de notificación y la plantilla de URL de notificación de ciclo de vida. Los hosts deben usar estos metadatos en lugar de codificar rutas de recursos de Teams de forma fija.

7. Prueba el canal objetivo

   Envía un mensaje en el canal de Teams seleccionado o activa un flujo que envíe a Teams. Si los mensajes no aparecen, vuelve a ejecutar la configuración y comprueba que los team_id y channel_id guardados todavía coincidan con el canal que abriste en Teams.

Opciones de configuración

Opción	Requerido	Descripción
client_id	Sí para configuración de Graph	Id de cliente de aplicación pública de Microsoft usado para OAuth con código de dispositivo
tenant_id	Generado	Id de tenant descubierto desde Microsoft Graph
team_id	Generado o seleccionado	Id de equipo de Teams usado para envíos de canal y suscripciones
team_name	Generado o seleccionado	Nombre visible del Team seleccionado
channel_id	Generado o seleccionado	Id de canal usado para envíos y suscripciones
channel_name	Generado o seleccionado	Nombre visible del canal seleccionado
desired_channel_name	No	Pista predeterminada/de búsqueda, y nombre para creación de canal cuando la creación está admitida
chat_id	No	Id de chat para suscripciones de chat cuando corresponda
ms_bot_app_id	Modo Bot Framework	Id de app de Microsoft Bot Framework
ms_bot_app_password	Modo Bot Framework	Contraseña de app de Bot Framework
bot_display_name	Modo Bot Framework	Nombre visible usado en flujos de trabajo del manifiesto de app de Teams
messaging_endpoint	Modo Bot Framework	Endpoint público de mensajería de Bot Framework

Nota

La salida de Teams y la configuración de suscripciones usan IDs, no nombres visibles. Las etiquetas se guardan para operadores y UIs de configuración, pero channel_id, team_id o chat_id siguen siendo los identificadores de runtime.

Precaución

Crear un canal de Teams que falta requiere el permiso delegado Channel.Create de Graph y un usuario con sesión iniciada que tenga permiso para crear canales en el Team seleccionado.

Funcionalidades

Mensajes de texto

- id: reply
  type: reply
  config:
    message: "Hello! How can I help you today?"

Formato Markdown

Teams admite un subconjunto de Markdown:

- id: formatted
  type: reply
  config:
    message: |
      **Bold** *Italic*
      - Bullet 1
      - Bullet 2
      [Link](https://example.com)

Adaptive Cards

Teams tiene soporte nativo para Adaptive Cards mediante adjuntos de Bot Framework. Usa la versión admitida por tu cliente de Teams objetivo y el modelo de acciones; las funcionalidades de Adaptive Cards 1.4, como Universal Actions, son específicas de escenarios de bot admitidos.

- id: send_card
  type: adaptive-card
  config:
    card:
      type: AdaptiveCard
      version: "1.4"
      body:
        - type: TextBlock
          text: "Welcome!"
          size: Large
          weight: Bolder
        - type: TextBlock
          text: "How can I assist you today?"
        - type: ActionSet
          actions:
            - type: Action.Submit
              title: "Get Help"
              data:
                action: "help"
            - type: Action.Submit
              title: "Create Ticket"
              data:
                action: "ticket"

Hero Cards

- id: hero_card
  type: reply
  config:
    hero_card:
      title: "Support Bot"
      subtitle: "Your AI Assistant"
      text: "I can help with technical issues, billing questions, and more."
      images:
        - url: "https://example.com/bot-image.png"
      buttons:
        - type: messageBack
          title: "Get Started"
          text: "get started"
          displayText: "Getting started..."

Sugerencias (respuestas rápidas)

- id: suggestions
  type: reply
  config:
    message: "What would you like to do?"
    suggested_actions:
      - title: "Check Status"
        value: "status"
      - title: "Create Ticket"
        value: "ticket"
      - title: "Contact Human"
        value: "human"

Adjuntos de archivos

- id: send_file
  type: reply
  config:
    message: "Here's your report"
    attachments:
      - contentType: "application/pdf"
        contentUrl: "https://example.com/report.pdf"
        name: "report.pdf"

Manejo de acciones de tarjetas

flows/on_card_action.ygtc

name: handle_card_action
version: "1.0"

nodes:
  - id: route_action
    type: branch
    config:
      conditions:
        - expression: "data.action == 'help'"
          to: show_help
        - expression: "data.action == 'ticket'"
          to: create_ticket
      default: unknown_action

  - id: show_help
    type: reply
    config:
      message: "Here's how I can help..."

triggers:
  - type: invoke
    name: "adaptiveCard/action"
    target: route_action

Configuración de canales

Canal de Team

greentic.demo.yaml

tenants:
  demo:
    teams:
      support:
        channels:
          teams:
            provider: messaging-teams
            config:
              team_id: "19:xxx@thread.tacv2"
              channel_id: "19:yyy@thread.tacv2"

Chat personal

Para chats personales 1:1 no se necesita configuración de canal. El bot responde a quien le envíe mensajes.

Mensajería proactiva

Envía mensajes sin iniciación del usuario:

- id: proactive
  type: reply
  config:
    message: "Reminder: Your ticket #123 needs attention"
    conversation_reference:
      conversation_id: "{{stored_conversation_id}}"
      service_url: "{{stored_service_url}}"

Nota

Guarda la referencia de conversación cuando los usuarios interactúen por primera vez con tu bot para habilitar la mensajería proactiva más adelante.

Solución de problemas

El bot no responde

1. Comprueba la configuración del endpoint en Azure Bot Service
2. Verifica que el certificado SSL sea válido
3. Comprueba que las credenciales de la app sean correctas
4. Revisa los registros de actividad en Azure

Error “Unauthorized”

• Verifica App ID y Password
• Comprueba el ID de tenant para apps de tenant único
• Asegúrate de que el bot esté habilitado en el canal de Teams

La tarjeta no se renderiza

• Valida el JSON de la tarjeta con Adaptive Cards Designer
• Comprueba que Teams admita la versión y el tipo de acción de la tarjeta
• Verifica que todos los campos requeridos estén presentes

Mensajes demorados

• Teams puede agrupar mensajes; esto es normal
• Comprueba el rendimiento de tu servidor
• Verifica que no haya limitación de velocidad

Seguridad

Precaución

Valida siempre los tokens de autenticación entrantes de Bot Framework para verificar que las solicitudes provienen de Microsoft.

Greentic valida automáticamente:

• Firma JWT
• Claims de emisor y audiencia
• Caducidad del token

Próximos pasos

• Adaptive Cards Designer - Diseña tarjetas visualmente
• Slack Provider - Agrega la integración de Slack
• WebChat Provider - Incrusta en sitios web