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/fetch
de 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, comtask/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ção
openUrl
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 atask/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:
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.
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
:
Esta imagem mostra um herói do Bot Framework cartão com uma açãoBuy
invoke
cartão. O valor da propriedadetype
étask/fetch
e o restante do objetovalue
pode ser de sua escolha.O bot recebe a mensagem HTTP POST
invoke
.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).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á amicrosoftTeams.tasks.submitTask()
função chamada posteriormente comosubmitTask()
para fins de legibilidade. Você pode chamarsubmitTask()
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 seusubmitHandler
. Passe-o como o primeiro parâmetro,result
. O Teams invocasubmitHandler
,err
énull
, eresult
é o objeto ou cadeia de caracteres que você passou parasubmitTask()
. Se você chamarsubmitTask()
com um parâmetroresult
, você deve passar umappId
ou uma matriz de cadeias de caracteresappId
. 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 mensagemtask/submit
incluindoresult
. Para obter mais informações, consulte conteúdo detask/fetch
etask/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 umtask/submit
quando o usuário seleciona qualquer botãoAction.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. |
{ |
O Teams exibe o valor de value em uma caixa de mensagem pop-up. |
{ |
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: { |
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#:
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;
}
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 |
---|---|
{ |
{ |
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
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de