Uso de cuadros de diálogo con bots

Invocar cuadros de diálogo (denominados módulos de tareas en TeamsJS v1.x) desde bots de Microsoft Teams mediante TaskFetchAction botones en tarjetas adaptables. Los diálogos proporcionan una interacción centrada abriendo 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 diálogos:

• Un nuevo mensaje task/fetchde invocación: el uso de la Action.Execute acción de tarjeta para tarjetas adaptables con task/fetch, ya sea un cuadro de diálogo basado en HTML o una 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 Action.OpenUrl acción de tarjeta para tarjetas adaptables. 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.

Nota:

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

Creación de un iniciador de diálogo

Para invocar un cuadro de diálogo desde un bot, envíe una tarjeta adaptable con TaskFetchAction botones. Cada botón incluye datos que el bot usa para determinar qué contenido de diálogo devolver.

Advertencia

Los servicios en la nube de Microsoft, incluidas las versiones web de los dominios de Teams, Outlook y Microsoft 365, se migran al *.cloud.microsoft dominio. Realice los pasos siguientes tan pronto como sea posible para asegurarse de que la aplicación continúa representándose en los hosts de cliente web de Microsoft 365 admitidos:

1. Actualice la biblioteca TeamsJS a v.2.19.0 o posterior. Debe llamar microsoftTeams.app.initialize() a para evitar ver una advertencia en el nuevo dominio. Para obtener más información sobre la versión más reciente de TeamsJS, consulte Biblioteca 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 sigue funcionando en aplicaciones host de Microsoft 365 existentes y futuras y minimiza la necesidad de cambios posteriores.

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

https://*.cloud.microsoft

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 ComprarAction.Execute tarjeta. 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, se controla mediante el OnAdaptiveCardAction controlador . Para obtener más información, vea Ejecución de acciones.

3. El bot crea un ActionResponse objeto y lo devuelve. Para obtener más información sobre el esquema de las respuestas, consulte la explicación sobre la tarea o el envío. El código siguiente proporciona un ejemplo del cuerpo de la respuesta 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 resultado se envía de vuelta 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 evento de envío de cuadro de diálogo 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) a desde la biblioteca cliente de TeamsJS, lo que desencadena el mismo evento de envío de cuadro de diálogo en la aplicación.

Controlar eventos de envío de cuadros de diálogo

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

Tipo de respuesta	Escenario
Sin respuesta	La respuesta más sencilla es no responder. El bot no es necesario para responder 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 cuadros de diálogo en .NET, TypeScript y Python:

.NET

using System.Text.Json;
using Microsoft.Teams.Api.TaskModules;
using Microsoft.Teams.Apps;
using Microsoft.Teams.Apps.Activities.Invokes;
using Microsoft.Teams.Apps.Annotations;
using Microsoft.Teams.Common.Logging;

[TaskSubmit]
public async Task<Microsoft.Teams.Api.TaskModules.Response> OnTaskSubmit([Context] Tasks.SubmitActivity activity, [Context] IContext.Client client, [Context] ILogger log)
{
    var data = activity.Value?.Data as JsonElement?;
    if (data == null)
    {
        log.Info("[TASK_SUBMIT] No data found in the activity value");
        return new Microsoft.Teams.Api.TaskModules.Response(
            new Microsoft.Teams.Api.TaskModules.MessageTask("No data found in the activity value"));
    }

    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 client.Send($"Hi {name}, thanks for submitting the form!");
            return new Microsoft.Teams.Api.TaskModules.Response(
                new Microsoft.Teams.Api.TaskModules.MessageTask("Form was submitted"));
        default:
            return new Microsoft.Teams.Api.TaskModules.Response(
                new Microsoft.Teams.Api.TaskModules.MessageTask("Unknown submission type"));
    }
}

TypeScript

import { App } from '@microsoft/teams.apps';
// ...

app.on('dialog.submit', async ({ activity, send, next }) => {
  const dialogType = activity.value.data?.submissiondialogtype;

  if (dialogType === 'simple_form') {
    const name = activity.value.data.name;
    await send(`Hi ${name}, thanks for submitting the form!`);
    return {
      task: {
        type: 'message',
        value: 'Form was submitted',
      },
    };
  }

  if (dialogType === 'webpage_dialog') {
    const name = activity.value.data.name;
    const email = activity.value.data.email;
    await send(`Hi ${name}, thanks for submitting the form! We got that your email is ${email}`);
    return {
      status: 200,
    };
  }
});

Python

from typing import Optional, Any
from microsoft_teams.api import TaskSubmitInvokeActivity, InvokeResponse, TaskModuleResponse, TaskModuleMessageResponse
from microsoft_teams.apps import ActivityContext

@app.on_dialog_submit
async def handle_dialog_submit(ctx: ActivityContext[TaskSubmitInvokeActivity]):
    data: Optional[Any] = ctx.activity.value.data
    dialog_type = data.get("submissiondialogtype") if data else None

    if dialog_type == "webpage_dialog":
        name = data.get("name") if data else None
        email = data.get("email") if data else None
        await ctx.send(f"Hi {name}, thanks for submitting the form! We got that your email is {email}")
        return InvokeResponse(
            body=TaskModuleResponse(task=TaskModuleMessageResponse(value="Form submitted successfully"))
        )

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 paso final devuelve un MessageTask para cerrar el cuadro de diálogo.

.NET

using System.Text.Json;
using Microsoft.Teams.Api;
using Microsoft.Teams.Api.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");

    var nextStepTaskInfo = new TaskInfo
    {
        Title = $"Thanks {nameStep1} - Get Email",
        Card = new Attachment
        {
            ContentType = new ContentType("application/vnd.microsoft.card.adaptive"),
            Content = nextStepCard
        }
    };

    return new Response(new ContinueTask(nextStepTaskInfo));

case "webpage_dialog_step_2":
    var nameStep2 = GetFormValue("name") ?? "Unknown";
    var emailStep2 = GetFormValue("email") ?? "No email";
    await client.Send($"Hi {nameStep2}, thanks for submitting the form! We got that your email is {emailStep2}");
    return new Response(new MessageTask("Multi-step form completed successfully"));

TypeScript

import { cardAttachment } from '@microsoft/teams.api';
import { AdaptiveCard, TextInput, SubmitAction } from '@microsoft/teams.cards';

// Return from dialog.submit handler to chain to the next step
const dialogCard = new AdaptiveCard(
  {
    type: 'TextBlock',
    text: 'This is a multi-step form',
    size: 'Large',
    weight: 'Bolder',
  },
  new TextInput()
    .withLabel('Name')
    .withIsRequired()
    .withId('name')
    .withPlaceholder('Enter your name')
)
  .withActions(
    new SubmitAction()
      .withTitle('Submit')
      .withData({ submissiondialogtype: 'webpage_dialog_step_1' })
  );

return {
  task: {
    type: 'continue',
    value: {
      title: 'Multi-step Form Dialog',
      card: cardAttachment('adaptive', dialogCard),
    },
  },
};

Python

# In your on_dialog_submit handler, return a ContinueTask to show the next step
from microsoft_teams.api import TaskModuleResponse, TaskModuleContinueResponse, CardTaskModuleTaskInfo
from microsoft_teams.cards import AdaptiveCard, TextInput, SubmitAction, Attachment

next_card = AdaptiveCard(
    body=[
        {"type": "TextBlock", "text": "Step 2: Enter 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": name}}
    ]
)

return InvokeResponse(
    body=TaskModuleResponse(
        task=TaskModuleContinueResponse(
            value=CardTaskModuleTaskInfo(
                title=f"Thanks {name} - Get Email",
                card=Attachment(content_type="application/vnd.microsoft.card.adaptive", content=next_card)
            )
        )
    )
)

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	Python
Bots de ejemplo de cuadro de diálogo-V4	Esta aplicación de ejemplo muestra cómo usar diálogos (denominados módulos de tareas en TeamsJS v1.x) mediante Bot Framework v4.	View	View	ND	Ver

Consulte también

• Tarjetas y diálogos
• Introducción a los cuadros de diálogo del SDK de Teams
• Tarjetas adaptables del SDK de Teams: acciones de ejecución
• Migración de BotBuilder al SDK de Teams