Usar caixas de diálogo com bots

Invoque caixas de diálogo (chamadas de módulos de tarefas no TeamsJS v1.x) de bots do Microsoft Teams usando TaskFetchAction botões em Cartões Adaptáveis. Os diálogos fornecem uma interação focada abrindo uma janela pop-up para o usuário, tornando-os ideais para formulários complexos ou fluxos de trabalho de várias etapas.

Há duas maneiras de invocar caixas de diálogo:

  • Uma nova mensagem task/fetchde invocação: Usando a Action.Execute ação card para Cartões Adaptáveis com task/fetch, uma caixa de diálogo baseada em HTML ou Cartão Adaptável é buscada dinamicamente do bot.
  • URLs de links profundos: usando a sintaxe de links profundos para caixas de diálogo, você pode usar a ação de Action.OpenUrl card para Cartões Adaptáveis. Com URLs de links profundos, a URL da caixa de diálogo ou o corpo do Cartão Adaptável já é conhecido por evitar uma viagem de ida e volta do servidor em relação a task/fetch.

Importante

Cada url e fallbackUrl deve implementar o protocolo de criptografia HTTPS.

Observação

No cliente do Teams v1, as caixas de diálogo eram chamadas de módulos de tarefa. Eles podem ocasionalmente ser usados como sinônimos.

Criar um iniciador de diálogo

Para invocar uma caixa de diálogo de um bot, envie um Cartão Adaptável com TaskFetchAction botões. Cada botão inclui dados que seu bot usa para determinar qual conteúdo da caixa de diálogo retornar.

Aviso

Os serviços de nuvem da Microsoft, incluindo versões Web dos domínios do Teams, Outlook e Microsoft 365, estão migrando para o *.cloud.microsoft domínio. Execute as etapas a seguir assim que possível para garantir que seu aplicativo continue a renderizar em hosts de cliente Web do Microsoft 365 com suporte:

  1. Atualize a biblioteca TeamsJS para v.2.19.0 ou posterior. Você deve ligar microsoftTeams.app.initialize() para evitar ver um aviso no novo domínio. Para obter mais informações sobre a versão mais recente do TeamsJS, consulte Biblioteca de cliente JavaScript do Microsoft Teams.

  2. Se você definiu cabeçalhos CSP ( Política de Segurança de Conteúdo ) para seu aplicativo, atualize a diretiva frame-ancestors para incluir o *.cloud.microsoft domínio. Para garantir a compatibilidade com versões anteriores durante a migração, mantenha os valores existentes frame-ancestors nos cabeçalhos CSP. Essa abordagem garante que seu aplicativo continue a funcionar em aplicativos host Microsoft 365 existentes e futuros e minimiza a necessidade de alterações subsequentes.

Atualize o seguinte domínio na frame-ancestors diretiva dos cabeçalhos CSP do seu aplicativo:

https://*.cloud.microsoft

tarefa/buscar solicitação ou resposta

As etapas a seguir fornecem instruções sobre como invocar uma caixa de diálogo (referida como módulo de tarefa no TeamsJS v1.x) usando task/fetch:

  1. Esta imagem mostra um Cartão Adaptável com uma ação ComprarAction.Execute card. O valor da propriedade type é task/fetch e o restante do objeto data pode ser de sua escolha.

  2. O bot recebe uma card.action atividade. No SDK do Teams, você lida com isso usando o OnAdaptiveCardAction manipulador. Para obter mais informações, consulte Executando ações.

  3. O bot cria um ActionResponse objeto e o retorna. Para obter mais informações sobre o esquema para respostas, consulte a discussão sobre tarefa/envio. O código a seguir fornece um exemplo do corpo da resposta que contém um objeto TaskInfo incorporado em um objeto wrapper:

    {
      "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"
        }
      }
    }
    

    O task/fetch evento e sua resposta para bots são semelhantes à microsoftTeams.tasks.startTask() função na biblioteca de cliente JavaScript do Microsoft Teams (TeamsJS).

  4. O Microsoft Teams exibe a caixa de diálogo.

A próxima seção fornece detalhes sobre como enviar o resultado de uma caixa de diálogo.

Enviar o resultado de um diálogo

Quando o usuário termina com a caixa de diálogo, o resultado é enviado de volta ao seu aplicativo. O funcionamento do envio depende do tipo de conteúdo da caixa de diálogo:

  • Cartão Adaptável (TaskInfo.card): quando o usuário seleciona um Action.Submit botão, o Teams envia um evento de envio de caixa de diálogo para seu aplicativo. O manipulador de envio de caixas de diálogo recebe os dados do formulário do card. Em C#, use o [TaskSubmit] atributo. Em TypeScript, use app.on('dialog.submit', ...). Em Python, use @app.on_dialog_submit.
  • Página da Web (TaskInfo.url): a página da Web chama microsoftTeams.tasks.submitTask(formData) da biblioteca de clientes TeamsJS, que dispara o mesmo evento de envio de caixa de diálogo em seu aplicativo.

Lidar com eventos de envio de diálogo

Quando o usuário envia uma caixa de diálogo, o bot recebe uma task/submit mensagem de invocação. Você tem várias opções ao responder:

Tipo de resposta Cenário
Sem resposta A resposta mais simples não é nenhuma resposta. Seu bot não é obrigado a responder quando o usuário termina com a caixa de diálogo.
MessageTask O Teams exibe uma mensagem em uma caixa de mensagem pop-up na caixa de diálogo.
ContinueTask Permite encadear sequências de Cartões Adaptáveis em uma experiência de assistente ou de várias etapas.

As guias a seguir mostram como lidar com eventos de envio de diálogo no .NET, TypeScript e Python:

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"));
    }
}

Encadeamento de caixas de diálogo em várias etapas

Você pode encadear Cartões Adaptáveis em um assistente de várias etapas retornando uma ContinueTask resposta do manipulador de envio. Cada etapa retorna um novo card e a etapa final retorna um MessageTask para fechar a caixa de diálogo.

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"));

Bot Framework ações do cartão vs. Ação do Cartão Adaptável.Enviar ações

O esquema para ações de card do Bot Framework é diferente das ações do Cartão Action.Submit Adaptável e a maneira de invocar caixas de diálogo também é diferente. O data objeto contém Action.Submit um msteams objeto para que ele não interfira em outras propriedades no card. A tabela a seguir mostra um exemplo de cada ação de cartão:

Bot Framework ação do cartão Ação De Cartão Adaptável.Enviar ação
{
"type": "invoke",
"title": "Comprar",
"value": {
"type": "task/fetch",
<...>
}
}
{
"type": "Action.Submit",
"id": "btnBuy",
"title": "Comprar",
"data": {
<...>,
"msteams": {
"type": "task/fetch"
}
}
}

Exemplo de código

Nome do exemplo Descrição .NET Node.js Manifesto Python
Bot de exemplo de caixa de diálogo-V4 Este aplicativo de exemplo demonstra como usar as caixas de diálogo (chamadas de módulos de tarefa no TeamsJS v1.x) usando o Bot Framework v4. View View NA Exibir

Confira também