Utilizar caixas de diálogo com bots

Invoque caixas de diálogo (referidos como módulos de tarefas no TeamsJS v1.x) a partir de bots do Microsoft Teams através de botões em Cartões Ajustáveis e cartões do Bot Framework que são heróis, miniaturas e conectores para Grupos do Microsoft 365. As caixas de diálogo são, muitas vezes, uma melhor experiência de utilizador do que vários passos de conversação. Acompanhe o estado do bot e permita que o usuário interrompa ou cancele a sequência.

Existem duas formas de invocar caixas de diálogo:

• Uma nova mensagem task/fetchde invocação: utilizar a açãoinvoke de cartão para cartões do Bot Framework ou a açãoAction.Submit de cartão para Cartões Ajustáveis, com task/fetch, é obtida dinamicamente uma caixa de diálogo baseada em CARTÃO HTML ou Adaptável a partir do bot.
• URLs de ligação avançada: ao utilizar a sintaxe de ligação avançada para caixas de diálogo, pode utilizar a açãoopenUrl de cartão para cartões do Bot Framework ou a açãoAction.OpenUrl de cartão para Cartões Ajustáveis, respetivamente. Com URLs de ligação avançada, o URL da caixa de diálogo ou o corpo do Cartão Adaptável já é conhecido por evitar um percurso de 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 com 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, existe um objeto TaskInfo incorporado num objeto wrapper, que o Teams utiliza para apresentar a caixa de diálogo (referida como módulo de tarefas no TeamsJS v1.x).

Aviso

Os serviços cloud da Microsoft, incluindo versões Web do Teams, Outlook e domínios do Microsoft 365, estão a migrar para o *.cloud.microsoft domínio. Execute os seguintes passos antes de setembro de 2024 para garantir que a sua aplicação continua a ser composta em anfitriões cliente Web do Microsoft 365 suportados:

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

2. Se tiver definido cabeçalhos de Política de Segurança de Conteúdo (CSP) para a sua aplicação, atualize a diretiva frame-predecessors para incluir o *.cloud.microsoft domínio. Para garantir a retrocompatibilidade durante a migração, mantenha os valores existentes frame-ancestors nos cabeçalhos do CSP. Esta abordagem garante que a sua aplicação continua a funcionar em aplicações anfitriãs existentes e futuras do Microsoft 365 e minimiza a necessidade de alterações subsequentes.

Atualize o seguinte domínio na frame-ancestors diretiva dos cabeçalhos CSP da sua aplicação:

https://*.cloud.microsoft

Os passos seguintes fornecem instruções sobre como invocar uma caixa de diálogo (referida como módulo de tarefas no TeamsJS v1.x) com task/fetch:

1. Esta imagem mostra um cartão herói do Bot Framework com umaaçãoComprarinvoke 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 o debate sobre tarefa/submissão. 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 a respetiva resposta para bots são semelhantes à microsoftTeams.tasks.startTask() função na biblioteca de cliente JavaScript (TeamsJS) do Microsoft Teams.

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

A secção seguinte fornece detalhes sobre como submeter o resultado de uma caixa de diálogo.

Submeter o resultado de uma caixa de diálogo

Quando o utilizador terminar a caixa de diálogo, submeter o resultado novamente para o bot é semelhante à forma como funciona com os separadores. Para obter mais informações, veja o exemplo de submissão 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 utilizador introduziu, chama a microsoftTeams.tasks.submitTask() função referida a partir daí como submitTask() para fins de legibilidade. Pode chamar submitTask() sem parâmetros se pretender que o Teams feche a caixa de diálogo (referida como módulo de tarefas no TeamsJS v1.x), mas tem de transmitir um objeto ou uma cadeia 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. Esta ação permite ao Teams confirmar que a aplicação que envia o resultado é a mesma, 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 secção seguinte fornece detalhes sobre como responder às task/submit mensagens.

Responde às task/submit mensagens

Quando o utilizador termina com uma caixa de diálogo (referida como módulo de tarefas no TeamsJS v1.x) invocada a partir de um bot, o bot recebe sempre 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. O bot não tem de responder quando o utilizador terminar a caixa de diálogo.
{ "tarefa": { "type": "message", "value": "Message text" } }	O Teams exibe o valor de value em uma caixa de mensagem pop-up.
{ "tarefa": { "type": "continue", "value": <taskInfo object> } }	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.

Payload de task/fetch e task/submit mensagens

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. No entanto, neste caso, é 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": { "theme": "default" | "escuro" | "contraste", }, "data": [campo de valor do cartão Bot Framework] | [campo de dados do Cartão Ajustável] }

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

Os seguintes separadores 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 das ações de cartão do Bot Framework é diferente das ações do Cartão Action.Submit Ajustável e a forma de invocar caixas de diálogo também é diferente. O data objeto no Action.Submit contém um msteams objeto para que não interfira com 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-V4 de exemplo de caixa de diálogo	Este exemplo mostra como criar caixas de diálogo com o Bot Framework v4 e o separador Teams.	View	View	View

Guias passo a passo

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

Confira também

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