Usar caixas de diálogo com bots

Invoque caixas de diálogo (conhecidas como módulos de tarefa no TeamsJS v1.x) de bots do Microsoft Teams usando botões em Cartões Adaptáveis e cartões Bot Framework que são heróis, miniaturas e conector para Grupos do Microsoft 365. As caixas de diálogo geralmente são uma experiência de usuário melhor do que várias etapas de conversa. Acompanhe o estado do bot e permita que o usuário interrompa ou cancele a sequência.

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

• Uma nova mensagem task/fetchde invocação: usar a açãoinvoke cartão para cartões Bot Framework ou a açãoAction.Submit cartão 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 link profundo: usando a sintaxe de link profundo para caixas de diálogo, você pode usar a açãoopenUrl cartão para cartões Bot Framework ou a açãoAction.OpenUrl cartão para Cartões Adaptáveis, respectivamente. Com URLs de link profundo, a URL da caixa de diálogo ou o corpo do Cartão Adaptável já é conhecido para evitar uma ida e volta do servidor em relação a task/fetch.

Importante

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

Invocar uma caixa de diálogo usando task/fetch

Quando o objeto value da ação de cartão invoke ou Action.Submit é inicializado e quando um usuário seleciona o botão, uma invoke mensagem é enviada ao bot. Na resposta HTTP à invoke mensagem, há um objeto TaskInfo inserido em um objeto wrapper, que o Teams usa para exibir a caixa de diálogo (conhecida como módulo de tarefa no TeamsJS v1.x).

Aviso

Os serviços de nuvem da Microsoft, incluindo versões web do Teams (teams.microsoft.com), outlook (outlook.com) e domínios do Microsoft 365 (microsoft365.com) estão migrando para o domínio cloud.microsoft . Execute as seguintes etapas antes de junho de 2024 para garantir que seu aplicativo continue a renderizar no cliente Web do Teams:

1. Atualize o SDK do TeamsJS para v.2.19.0 ou superior. Para obter mais informações sobre a versão mais recente do SDK do TeamsJS, consulte Biblioteca de clientes JavaScript do Microsoft Teams.

2. Atualize os cabeçalhos da Política de Segurança de Conteúdo em seu aplicativo do Teams para permitir que seu aplicativo acesse o domínio teams.cloud.microsoft . Se o aplicativo do Teams se estender pelo Outlook e pelo Microsoft 365, verifique se você permitirá que seu aplicativo acesse teams.cloud.microsoft, outlook.cloud.microsoft e domínios m365.cloud.microsoft .

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

1. Esta imagem mostra um herói do Bot Framework cartão com uma açãoBuyinvoke cartão. O valor da propriedade type é task/fetch e o restante do objeto value pode ser de sua escolha.

2. O bot recebe a mensagem HTTP POST invoke.

3. O bot cria um objeto de resposta e o retorna no corpo da resposta POST com um código de resposta HTTP 200. Para obter mais informações sobre o esquema de respostas, consulte a discussão sobre tarefa/envio. O código a seguir fornece um exemplo de corpo da resposta HTTP que contém um objeto TaskInfo inserido 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 clientes 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 uma caixa de diálogo

Quando o usuário é concluído com a caixa de diálogo, enviar o resultado de volta para o bot é semelhante à maneira como ele funciona com guias. Para obter mais informações, consulte exemplo de envio do resultado de uma caixa de diálogo. Há algumas diferenças da seguinte maneira:

• HTML ou JavaScript que é TaskInfo.url: depois de validar o que o usuário inseriu, você chamará a microsoftTeams.tasks.submitTask() função chamada posteriormente como submitTask() para fins de legibilidade. Você pode chamar submitTask() sem parâmetros se quiser que o Teams feche a caixa de diálogo (chamado de módulo de tarefa no TeamsJS v1.x), mas deve passar um objeto ou uma cadeia de caracteres para o seu submitHandler. Passe-o como o primeiro parâmetro, result. O Teams invoca submitHandler, err é null, e result é o objeto ou cadeia de caracteres que você passou para submitTask(). Se você chamar submitTask() com um parâmetro result, você deve passar um appId ou uma matriz de cadeias de caracteres appId. Essa ação permite que o Teams valide que o aplicativo que envia o resultado é o mesmo, que invocou a caixa de diálogo. Seu bot recebe uma mensagem task/submit incluindo result. Para obter mais informações, consulte conteúdo de task/fetch e task/submit.
• Cartão Adaptável que é TaskInfo.card: o corpo do Cartão Adaptável preenchido pelo usuário é enviado ao bot por meio de um task/submit quando o usuário seleciona qualquer botão Action.Submit.

A próxima seção fornece detalhes sobre como responder às task/submit mensagens.

Responde às task/submit mensagens

Quando o usuário termina com uma caixa de diálogo (chamada de módulo de tarefa no TeamsJS v1.x) invocada de um bot, o bot sempre recebe uma task/submit invoke mensagem. Você tem várias opções ao responder à mensagem task/submit da seguinte maneira:

Resposta do corpo HTTP	Cenário
Nenhum ignora a task/submit mensagem	A resposta mais simples não é nenhuma resposta. Seu bot não é necessário para responder quando o usuário é concluído com a caixa de diálogo.
{ "tarefa": { "type": "message", "value": "Texto da mensagem" } }	O Teams exibe o valor de value em uma caixa de mensagem pop-up.
{ "tarefa": { "type": "continue", "value": <objeto TaskInfo> } }	Permite encadear sequências de Cartões Adaptáveis em uma experiência de assistente ou de várias etapas.

Observação

O encadeamento Cartões Adaptáveis em uma sequência é um cenário avançado. O aplicativo de exemplo Node.js dá suporte a ele. Para obter mais informações, consulte a caixa de diálogo do Microsoft Teams Node.js.

A próxima seção fornece detalhes sobre o conteúdo das mensagens task/fetch e task/submit.

Carga de task/fetch mensagens e task/submit

Esta seção define o esquema do que seu bot recebe quando recebe um objeto task/fetch ou task/submit Bot Framework Activity. A tabela a seguir fornece as propriedades de conteúdo das mensagens task/fetch e task/submit:

Propriedade	Descrição
type	É sempre invoke.
name	É task/fetch ou task/submit.
value	É a carga definida pelo desenvolvedor. A estrutura do objeto value é igual ao que é enviado do Teams. Nesse caso, no entanto, é diferente. Ele requer suporte para uma pesquisa dinâmica que é task/fetch de ambos os Bot Framework, que é value e as ações Action.Submit, que são data. Uma maneira de comunicar o Teams context ao bot é necessária além do que está incluído no value ou data. Combine 'value' e 'data' em um objeto pai: { "context": { "tema": "padrão" | "escuro" | "contraste", }, "data": [campo de valor do Bot Framework cartão] | [campo de dados do Cartão Adaptável] }

A próxima seção fornece um exemplo de recebimento e resposta a task/fetch e task/submit invocam mensagens no Node.js.

As seguintes guias fornecem task/fetch e task/submit invocam mensagens em Node.js e C#:

Node.js

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

C#

protected override Task<TaskModuleResponse> OnTeamsTaskModuleFetchAsync(ITurnContext<IInvokeActivity> turnContext, TaskModuleRequest taskModuleRequest, CancellationToken cancellationToken)
{
    var asJobject = JObject.FromObject(taskModuleRequest.Data);
    var value = asJobject.ToObject<CardTaskFetchValue<string>>()?.Data;

    var taskInfo = new TaskModuleTaskInfo();
    switch (value)
    {
        case TaskModuleIds.YouTube:
            taskInfo.Url = taskInfo.FallbackUrl = _baseUrl + "/" + TaskModuleIds.YouTube;
            SetTaskInfo(taskInfo, TaskModuleUIConstants.YouTube);
            break;
        case TaskModuleIds.CustomForm:
            taskInfo.Url = taskInfo.FallbackUrl = _baseUrl + "/" + TaskModuleIds.CustomForm;
            SetTaskInfo(taskInfo, TaskModuleUIConstants.CustomForm);
            break;
        case TaskModuleIds.AdaptiveCard:
            taskInfo.Card = CreateAdaptiveCardAttachment();
            SetTaskInfo(taskInfo, TaskModuleUIConstants.AdaptiveCard);
            break;
        default:
            break;
    }

    return Task.FromResult(taskInfo.ToTaskModuleResponse());
}

protected override async Task<TaskModuleResponse> OnTeamsTaskModuleSubmitAsync(ITurnContext<IInvokeActivity> turnContext, TaskModuleRequest taskModuleRequest, CancellationToken cancellationToken)
{
    var reply = MessageFactory.Text("OnTeamsTaskModuleSubmitAsync Value: " + JsonConvert.SerializeObject(taskModuleRequest));
    await turnContext.SendActivityAsync(reply, cancellationToken);

    return TaskModuleResponseFactory.CreateResponse("Thanks!");
}

private static void SetTaskInfo(TaskModuleTaskInfo taskInfo, UISettings uIConstants)
{
    taskInfo.Height = uIConstants.Height;
    taskInfo.Width = uIConstants.Width;
    taskInfo.Title = uIConstants.Title.ToString();
}

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

O esquema para ações do Bot Framework cartão é 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 no Action.Submit contém um msteams objeto para que ele não interfira em outras propriedades no cartão. 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": "Buy", "value": { "type": "task/fetch", <...> } }	{ "type": "Action.Submit", "id": "btnBuy", "title": "Buy", "data": { <...>, "msteams": { "type": "task/fetch" } } }

Exemplo de código

Nome do exemplo	Descrição	.NET	Node.js	Manifesto
Bots de exemplo de caixa de diálogo-V4	Este exemplo mostra como criar caixas de diálogo usando a guia Bot Framework v4 e Teams.	View	View	View

Guias passo a passo

Siga o guia passo a passo para criar e buscar o bot de diálogo no Teams.

Confira também

• Cartões e caixas de diálogo
• Código de exemplo de caixa de diálogo do Microsoft Teams no Node.js
• Amostras de estrutura de bot