Usar diálogos con bots

Invocar diálogos (denominados módulos de tareas en TeamsJS v1.x) desde bots de Microsoft Teams mediante TaskFetchAction botones en tarjetas adaptables. Los cuadros de diálogo proporcionan una interacción enfocada al abrir una ventana emergente para el usuario, lo que los hace ideales para formularios complejos o flujos de trabajo de varios pasos.

Hay dos maneras de invocar los diálogos:

  • Un nuevo mensaje task/fetchde invocación: El uso de la acción de tarjeta Action.Execute para tarjetas adaptables con task/fetch, un cuadro de diálogo HTML o basado en tarjeta adaptable se obtiene dinámicamente del bot.
  • Direcciones URL de vínculo profundo: con la sintaxis de vínculo profundo para cuadros de diálogo, puede usar la acción de Action.OpenUrl tarjeta para tarjetas adaptables. Con las direcciones URL de vínculo profundo, la dirección URL del cuadro de diálogo o el cuerpo de la tarjeta adaptable ya se conoce para evitar un viaje de ida y vuelta del servidor en relación con task/fetch.

Importante

Cada url y fallbackUrl debe implementar el protocolo de encriptación HTTPS.

Nota:

En el cliente de Teams v1, los cuadros de diálogo se llamaban módulos de tareas. Ocasionalmente se pueden usar como sinónimos.

Crear un iniciador de cuadro de diálogo

Para invocar un cuadro de diálogo desde un bot, envíe una tarjeta adaptativa con TaskFetchAction bots. Cada botón incluye datos que el bot usa para determinar el contenido del cuadro de diálogo que se devolverá.

Advertencia

Los servicios en la nube de Microsoft, incluidas las versiones web de Teams, Outlook y dominios de Microsoft 365, están migrando al *.cloud.microsoft dominio. Realice los pasos siguientes tan pronto como sea posible para asegurarse de que la aplicación se siga representando en los hosts de cliente web de Microsoft 365 compatibles:

  1. Actualice la biblioteca TeamsJS a la versión 2.19.0 o posterior. Debe llamar microsoftTeams.app.initialize() para evitar ver una advertencia en el dominio nuevo. Para obtener más información sobre la versión más reciente de TeamsJS, consulte la biblioteca de cliente JavaScript de Microsoft Teams.

  2. Si ha definido encabezados de directiva de seguridad de contenido (CSP) para la aplicación, actualice la directiva frame-ancestors para incluir el *.cloud.microsoft dominio. Para garantizar la compatibilidad con versiones anteriores durante la migración, conserve los valores existentes frame-ancestors en los encabezados de CSP. Este enfoque garantiza que la aplicación siga funcionando en las aplicaciones host de Microsoft 365 existentes y futuras y minimiza la necesidad de cambios posteriores.

Actualice el siguiente dominio en la directiva de los encabezados CSP de la frame-ancestors aplicación:

https://*.cloud.microsoft

solicitud o respuesta a tarea/recuperar opción recuperar tarea

En los pasos siguientes se proporcionan instrucciones sobre cómo invocar un cuadro de diálogo (denominado módulo de tareas en TeamsJS v1.x) mediante task/fetch:

  1. Esta imagen muestra una tarjeta adaptable con una acción de tarjeta de compraAction.Execute . El valor de la type propiedad es task/fetch y el resto del data objeto puede ser de su elección.

  2. El bot recibe una card.action actividad. En el SDK de Teams, esto se controla mediante el OnAdaptiveCardAction controlador. Para obtener más información, consulte Ejecución de acciones.

  3. El bot crea un ActionResponse objeto y lo devuelve. Para obtener más información sobre el esquema de respuestas, consulte la discusión sobre tarea/envío. El código siguiente proporciona un ejemplo del cuerpo de la respuesta que contiene un objeto TaskInfo incrustado en un objeto envolvente:

    {
      "task": {
        "type": "continue",
        "value": {
          "title": "Task module title",
          "height": 500,
          "width": "medium",
          "url": "https://contoso.com/msteams/taskmodules/newcustomer",
          "fallbackUrl": "https://contoso.com/msteams/taskmodules/newcustomer"
        }
      }
    }
    

    El task/fetch evento y su respuesta para los bots es similar a la microsoftTeams.tasks.startTask() función de la biblioteca de cliente JavaScript de Microsoft Teams (TeamsJS).

  4. Microsoft Teams muestra el cuadro de diálogo.

En la siguiente sección se proporcionan detalles sobre cómo enviar el resultado de un diálogo.

Enviar el resultado de un diálogo

Cuando el usuario termina con el cuadro de diálogo, el resultado se vuelve a enviar a la aplicación. El funcionamiento del envío depende del tipo de contenido del cuadro de diálogo:

  • Tarjeta adaptable (TaskInfo.card): cuando el usuario selecciona un Action.Submit botón, Teams envía un cuadro de diálogo para enviar eventos a la aplicación. El controlador de envío del cuadro de diálogo recibe los datos del formulario de la tarjeta. En C#, use el [TaskSubmit] atributo. En TypeScript, use app.on('dialog.submit', ...). En Python, use @app.on_dialog_submit.
  • Página web (TaskInfo.url): la página web llama microsoftTeams.tasks.submitTask(formData) desde la biblioteca cliente TeamsJS, que desencadena el mismo evento de envío de cuadro de diálogo en la aplicación.

Gestionar eventos de envío de diálogos

Cuando el usuario envía un cuadro de diálogo, el bot recibe un task/submit mensaje de invocación. Tienes varias opciones a la hora de responder:

Tipo de respuesta Escenario
Sin respuesta La respuesta más sencilla es no responder. No es necesario que el bot responda cuando el usuario termina con el cuadro de diálogo.
MessageTask Teams muestra un mensaje en un cuadro de mensaje emergente en el cuadro de diálogo.
ContinueTask Permite encadenar secuencias de tarjetas adaptables en una experiencia de asistente o de varios pasos.

En las pestañas siguientes se muestra cómo controlar los eventos de envío de diálogos en .NET, TypeScript y Python:

using System.Text.Json;
using Microsoft.Teams.Apps;
using Microsoft.Teams.Apps.TaskModules;

teams.OnTaskSubmit(async (context, cancellationToken) =>
{
  var data = context.Activity.Value?.Data as JsonElement?;
    if (data == null)
    {
    return TaskModuleResponse.CreateBuilder()
      .WithType(TaskModuleResponseTypes.Message)
      .WithMessage("No data found in the activity value")
      .Build();
    }

    var submissionType = data.Value.TryGetProperty("submissiondialogtype", out var submissionTypeObj) && submissionTypeObj.ValueKind == JsonValueKind.String
        ? submissionTypeObj.ToString()
        : null;

    string? GetFormValue(string key)
    {
        if (data.Value.TryGetProperty(key, out var val))
        {
            if (val is JsonElement element)
                return element.GetString();
            return val.ToString();
        }
        return null;
    }

    switch (submissionType)
    {
        case "simple_form":
            var name = GetFormValue("name") ?? "Unknown";
            await context.SendAsync($"Hi {name}, thanks for submitting the form!", cancellationToken);
            return TaskModuleResponse.CreateBuilder()
              .WithType(TaskModuleResponseTypes.Message)
              .WithMessage("Form was submitted")
              .Build();
        default:
            return TaskModuleResponse.CreateBuilder()
              .WithType(TaskModuleResponseTypes.Message)
              .WithMessage("Unknown submission type")
              .Build();
    }
      });

Encadenamiento de diálogos de varios pasos

Puede encadenar tarjetas adaptables en un asistente de varios pasos devolviendo una ContinueTask respuesta del controlador de envío. Cada paso devuelve una nueva tarjeta y el último devuelve una MessageTask para cerrar el cuadro de diálogo.

using System.Text.Json;
using Microsoft.Teams.Apps;
using Microsoft.Teams.Apps.Schema;
using Microsoft.Teams.Apps.TaskModules;
using Microsoft.Teams.Cards;

// Add these cases to your OnTaskSubmit method
case "webpage_dialog_step_1":
    var nameStep1 = GetFormValue("name") ?? "Unknown";
    var nextStepCardJson = $$"""
    {
        "type": "AdaptiveCard",
        "version": "1.4",
        "body": [
            {
                "type": "TextBlock",
                "text": "Email",
                "size": "Large",
                "weight": "Bolder"
            },
            {
                "type": "Input.Text",
                "id": "email",
                "label": "Email",
                "placeholder": "Enter your email",
                "isRequired": true
            }
        ],
        "actions": [
            {
                "type": "Action.Submit",
                "title": "Submit",
                "data": {"submissiondialogtype": "webpage_dialog_step_2", "name": "{{nameStep1}}"}
            }
        ]
    }
    """;

    var nextStepCard = JsonSerializer.Deserialize<AdaptiveCard>(nextStepCardJson)
        ?? throw new InvalidOperationException("Failed to deserialize next step card");

    TeamsAttachment nextStepAttachment = TeamsAttachment.CreateBuilder()
      .WithAdaptiveCard(JsonSerializer.SerializeToElement(nextStepCard))
      .Build();

    return TaskModuleResponse.CreateBuilder()
      .WithType(TaskModuleResponseTypes.Continue)
      .WithTitle($"Thanks {nameStep1} - Get Email")
      .WithCard(nextStepAttachment)
      .Build();

case "webpage_dialog_step_2":
    var nameStep2 = GetFormValue("name") ?? "Unknown";
    var emailStep2 = GetFormValue("email") ?? "No email";
    await context.SendAsync($"Hi {nameStep2}, thanks for submitting the form! We got that your email is {emailStep2}", cancellationToken);
    return TaskModuleResponse.CreateBuilder()
      .WithType(TaskModuleResponseTypes.Message)
      .WithMessage("Multi-step form completed successfully")
      .Build();

Acciones de tarjeta de Bot Framework vs. Acciones de tarjeta adaptable. Enviar acciones

El esquema de las acciones de tarjeta de Bot Framework es diferente de las acciones de tarjeta Action.Submit adaptables y la forma de invocar cuadros de diálogo también lo es. El data objeto contiene Action.Submit un msteams objeto para que no interfiera con otras propiedades de la tarjeta. La siguiente tabla muestra un ejemplo de cada acción de la tarjeta:

Acción de la tarjeta de Bot Framework Acción de tarjeta adaptable. Enviar acción
{
"type": "invoke",
"title": "Buy",
"value": {
"type": "task/fetch",
<...>
}
}
{
"type": "Action.Submit",
"id": "btnBuy",
"title": "Buy",
"data": {
<...>,
"msteams": {
"type": "task/fetch"
}
}
}

Ejemplo de código

Ejemplo de nombre Descripción .NET Node.js Manifiesto Python
Cuadro de diálogo bots de ejemplo-V4 En esta aplicación de ejemplo, se muestra cómo usar cuadros de diálogo (denominados módulos de tareas en TeamsJS v1.x) con Bot Framework v4. View View ND Ver

Consulte también