Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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 aAction.Executeação card para Cartões Adaptáveis comtask/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.OpenUrlcard 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 atask/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:
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.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.microsoftdomínio. Para garantir a compatibilidade com versões anteriores durante a migração, mantenha os valores existentesframe-ancestorsnos 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
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:
Esta imagem mostra um Cartão Adaptável com uma ação Comprar
Action.Executecard. O valor da propriedadetypeétask/fetche o restante do objetodatapode ser de sua escolha.O bot recebe uma
card.actionatividade. No SDK do Teams, você lida com isso usando oOnAdaptiveCardActionmanipulador. Para obter mais informações, consulte Executando ações.O bot cria um
ActionResponseobjeto 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/fetchevento e sua resposta para bots são semelhantes àmicrosoftTeams.tasks.startTask()função na biblioteca de cliente JavaScript do Microsoft Teams (TeamsJS).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.Submitbotã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, useapp.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 |
|---|---|
{ |
{ |
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 |