Uso de cuadros de diálogo con bots

  • Artículo

Invocar cuadros de diálogo (denominados módulos de tareas en TeamsJS v1.x) desde bots de Microsoft Teams mediante botones en tarjetas adaptables y tarjetas de Bot Framework que son héroes, miniaturas y conectores para Grupos de Microsoft 365. Los diálogos suelen ser una mejor experiencia de usuario que varios pasos de conversación. Realizar un seguimiento del estado del bot y permitir al usuario interrumpir o cancelar la secuencia.

Hay dos maneras de invocar diálogos:

  • Un nuevo mensaje task/fetchde invocación: el uso de la invokeacción de tarjeta para las tarjetas de Bot Framework o la Action.Submitacción de tarjeta para tarjetas adaptables, con task/fetch, un cuadro de diálogo basado en HTML o tarjeta adaptable se captura dinámicamente desde el bot.
  • Direcciones URL de vínculo profundo: con la sintaxis de vínculo profundo para los diálogos, puede usar la openUrlacción de tarjeta para las tarjetas de Bot Framework o la Action.OpenUrlacción de tarjeta para tarjetas adaptables, respectivamente. Con las direcciones URL de vínculo profundo, ya se sabe que la dirección URL del cuadro de diálogo o el cuerpo de la tarjeta adaptable evitan un recorrido 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.

Invocación de un cuadro de diálogo mediante task/fetch

Cuando el value objeto de la invoke acción de la tarjeta o Action.Submit se inicializa y cuando un usuario selecciona el botón, se envía un invoke mensaje al bot. En la respuesta HTTP al invoke mensaje, hay un objeto TaskInfo incrustado en un objeto contenedor, que Teams usa para mostrar el cuadro de diálogo (denominado módulo de tareas en TeamsJS v1.x).

Advertencia

Los servicios en la nube de Microsoft, incluidas las versiones web de los dominios de Teams (teams.microsoft.com), Outlook (outlook.com) y Microsoft 365 (microsoft365.com) se migran al dominio cloud.microsoft . Realice los pasos siguientes antes de junio de 2024 para asegurarse de que la aplicación continúa representándose en el cliente web de Teams:

  1. Actualice el SDK de TeamsJS a la versión 2.19.0 o posterior. Para obtener más información sobre la versión más reciente del SDK de TeamsJS, consulte Biblioteca cliente JavaScript de Microsoft Teams.

  2. Actualice los encabezados de la directiva de seguridad de contenido en la aplicación de Teams para permitir que la aplicación acceda al dominio teams.cloud.microsoft . Si la aplicación de Teams se extiende a través de Outlook y Microsoft 365, asegúrese de permitir que la aplicación acceda a los dominios teams.cloud.microsoft, outlook.cloud.microsoft y m365.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 principal de Bot Framework con una acción Comprarinvoketarjeta. El valor de la type propiedad es task/fetch y el resto del value objeto puede ser de su elección.

  2. El bot recibe el mensaje invoke HTTP POST.

  3. El bot crea un objeto de respuesta y lo devuelve en el cuerpo de la respuesta POST con un código de respuesta HTTP 200. Para obtener más información sobre el esquema de las respuestas, consulte la explicación sobre la tarea o el envío. El siguiente código proporciona un ejemplo de cuerpo de la respuesta HTTP que contiene un objeto TaskInfo incrustado en un objeto contenedor:

    {
  "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 cliente JavaScript de Microsoft Teams (TeamsJS).

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

En la sección siguiente se proporcionan detalles sobre el envío del resultado de un cuadro de diálogo.

Enviar el resultado de un cuadro de diálogo

Cuando el usuario termina con el cuadro de diálogo, el envío del resultado al bot es similar al modo en que funciona con pestañas. Para obtener más información, vea el ejemplo de envío del resultado de un cuadro de diálogo. Hay algunas diferencias como las siguientes:

  • HTML o JavaScript que es TaskInfo.url: una vez que haya validado lo que el usuario ha especificado, llame a la función a la microsoftTeams.tasks.submitTask() que se hace referencia en lo sucesivo con submitTask() fines de legibilidad. Puede llamar a submitTask() sin ningún parámetro si desea que Teams cierre el cuadro de diálogo (denominado módulo de tareas en TeamsJS v1.x), pero debe pasar un objeto o una cadena a submitHandler. Páselo como primer parámetro, result. Teams invoca submitHandler, erres null, y result es el objeto o la cadena que se ha pasado a submitTask(). Si llamasubmitTask() con un result parámetro, debe pasar una appId o una matriz de appId cadenas. Esta acción permite a Teams validar que la aplicación que envía el resultado es la misma, que invocó el cuadro de diálogo. Tu bot recibe un task/submitmensaje que incluye result. Para obtener más información, consulte carga de task/fetch y task/submit los mensajes.
  • Tarjeta adaptable que es TaskInfo.card: el cuerpo de la tarjeta adaptable rellenado por el usuario se envía al bot a través de un task/submit mensaje cuando el usuario selecciona cualquier Action.Submit botón.

En la sección siguiente se proporcionan detalles sobre cómo responder a los task/submit mensajes.

Responde a los task/submit mensajes

Cuando el usuario termina con un cuadro de diálogo (denominado módulo de tareas en TeamsJS v1.x) invocado desde un bot, el bot siempre recibe un task/submit invoke mensaje. A la hora de responder al task/submit mensaje, tiene varias opciones, como se indica a continuación:

Respuesta del cuerpo HTTP Escenario
Ninguno omite el task/submit mensaje La respuesta más sencilla es no responder. No es necesario que el bot responda cuando el usuario haya terminado con el cuadro de diálogo. 
{
  "task": {
    "type": "message",
    "value": "Message text"
  }
}
 Teams muestra el valor de value en un cuadro de mensaje emergente. 
{
  "task": {
    "type": "continue",
    "value": <Objeto TaskInfo>
  }
}
 Permite encadenar secuencias de tarjetas adaptables en una experiencia de asistente o de varios pasos.

Nota:

Encadenamiento de tarjetas adaptables en una secuencia es un escenario avanzado. La aplicación de ejemplo Node.js lo admite. Para obtener más información, vea Cuadro de diálogo de Microsoft Teams Node.js.

La siguiente sección proporciona detalles sobre la carga de task/fetch y task/submit los mensajes.

Carga útil de task/fetch y task/submit mensajes

Esta sección define el esquema de lo que recibe su bot cuando recibe un task/fetch o task/submit objeto de Bot FrameworkActivity. La siguiente tabla proporciona las propiedades de la carga de task/fetch y task/submit los mensajes:

Propiedad Descripción
type Siempre es invoke.
name Es task/fetch o task/submit.
value Es la carga definida por el desarrollador. La estructura del value objeto es la misma que se envía desde Teams. En este caso, sin embargo, es diferente. Requiere compatibilidad con la recuperación dinámica que procede task/fetch de Bot Framework, que es value y acciones de tarjeta Action.Submit adaptable, que es data. Es necesario una forma de comunicar de Teams context al bot además de lo que se incluye envalue o data.

Combina "valor" y "datos" en un objeto primario:

{
  "context": {
    "theme": "default" | "oscuro" | "contraste",
  },
  "data": [campo de valor de la tarjeta de Bot Framework] | [campo de datos de la tarjeta adaptable]
}

La siguiente sección proporciona un ejemplo de recepción y respuesta a task/fetch y task/submit de mensajes de invocación en Node.js.

Las pestañas siguientes proporcionan task/fetch e task/submit invocan mensajes en Node.js y C#:

handleTeamsTaskModuleFetch(context, taskModuleRequest) {
    // Called when the user selects an options from the displayed HeroCard or
    // AdaptiveCard.  The result is the action to perform.

    const cardTaskFetchValue = taskModuleRequest.data.data;
    var taskInfo = {}; // TaskModuleTaskInfo

    if (cardTaskFetchValue === TaskModuleIds.YouTube) {
        // Display the YouTube.html page
        taskInfo.url = taskInfo.fallbackUrl = this.baseUrl + '/' + TaskModuleIds.YouTube + '.html';
        this.setTaskInfo(taskInfo, TaskModuleUIConstants.YouTube);
    } else if (cardTaskFetchValue === TaskModuleIds.CustomForm) {
        // Display the CustomForm.html page, and post the form data back via
        // handleTeamsTaskModuleSubmit.
        taskInfo.url = taskInfo.fallbackUrl = this.baseUrl + '/' + TaskModuleIds.CustomForm + '.html';
        this.setTaskInfo(taskInfo, TaskModuleUIConstants.CustomForm);
    } else if (cardTaskFetchValue === TaskModuleIds.AdaptiveCard) {
        // Display an AdaptiveCard to prompt user for text, and post it back via
        // handleTeamsTaskModuleSubmit.
        taskInfo.card = this.createAdaptiveCardAttachment();
        this.setTaskInfo(taskInfo, TaskModuleUIConstants.AdaptiveCard);
    }

    return TaskModuleResponseFactory.toTaskModuleResponse(taskInfo);
}

async handleTeamsTaskModuleSubmit(context, taskModuleRequest) {
    // Called when data is being returned from the selected option (see `handleTeamsTaskModuleFetch').

    // Echo the users input back.  In a production bot, this is where you'd add behavior in
    // response to the input.
    await context.sendActivity(MessageFactory.text('handleTeamsTaskModuleSubmit: ' + JSON.stringify(taskModuleRequest.data)));

    // Return TaskModuleResponse
    return {
        // TaskModuleMessageResponse
        task: {
            type: 'message',
            value: 'Thanks!'
        }
    };
}

setTaskInfo(taskInfo, uiSettings) {
    taskInfo.height = uiSettings.height;
    taskInfo.width = uiSettings.width;
    taskInfo.title = uiSettings.title;
}

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 adaptable y la manera de invocar diálogos también es diferente. El data objeto de Action.Submit contiene 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
Bots de ejemplo de cuadro de diálogo-V4 En este ejemplo se muestra cómo crear diálogos mediante Bot Framework v4 y la pestaña Teams. View View View

Guía paso a paso

Siga la guía paso a paso para crear y capturar un bot de diálogo en Teams.

Consulte también