Responder à ação de submissão da caixa de diálogo

  • Artigo

Importante

Os exemplos de código nesta secção baseiam-se na v4.6 e versões posteriores do SDK do Bot Framework. Se estiver à procura de documentação para versões anteriores, veja a secção Extensões de Mensagens – SDK v3 na pasta Recursos da documentação.

Este documento orienta-o sobre a forma como a sua aplicação responde aos comandos de ação, como a caixa de diálogo do utilizador (referida como módulo de tarefas no TeamsJS v1.x) submeter a ação. Depois de um utilizador submeter a caixa de diálogo, o serviço Web recebe uma composeExtensions/submitAction mensagem de invocação com o ID de comando e os valores dos parâmetros. A sua aplicação tem cinco segundos para responder à invocação.

Você tem as seguintes opções para responder:

Se a aplicação não responder dentro de cinco segundos, o cliente do Teams repetirá o pedido duas vezes antes de enviar uma mensagem de erro Não é possível aceder à aplicação. Se o bot responder após o tempo limite, a resposta será ignorada.

Observação

  • A aplicação tem de adiar quaisquer ações de execução prolongada após o bot responder ao pedido de invocação. Os resultados da ação de execução prolongada podem ser entregues como uma mensagem.
  • A sua aplicação tem cinco segundos para responder à mensagem de invocação.

Para autenticação ou configuração, depois que o usuário concluir o processo, a invocação original será reenviada para seu serviço Web. A tabela seguinte mostra que tipos de respostas estão disponíveis, com base na localização de invocação commandContext da extensão da mensagem:

Tipo de Resposta Escrever Barra de comando Mensagem
Resposta do cartão ✔️ ✔️ ✔️
Outra caixa de diálogo ✔️ ✔️ ✔️
Bot com Cartão Adaptável ✔️ ❌ ✔️
Sem resposta ✔️ ✔️ ✔️

Observação

  • Quando seleciona Action.Submit através de cartões ME, este envia a atividade de invocação com o nome composeExtensions, em que o valor é igual ao payload habitual.
  • Quando você seleciona Action.Submit por meio de conversa, você recebe uma atividade de mensagem com o nome onCardButtonClicked, em que o valor é igual ao conteúdo normal.

Se a aplicação contiver um bot de conversação, instale o bot na conversação e, em seguida, carregue a caixa de diálogo. O bot é útil para obter mais contexto para a caixa de diálogo. Para instalar o bot de conversação, consulte Solicitação para instalar o bot de conversa.

O evento de invocação submitAction

Exemplos de recebimento da mensagem de invocação são os seguintes:

protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionSubmitActionAsync(
  ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken) {
  //code to handle the submit action
}

Responder com um cartão inserido na área de mensagem de redação

A maneira mais comum de responder à solicitação composeExtensions/submitAction é com um cartão inserido na área de mensagem de redação. O usuário envia o cartão para a conversa. Para obter mais informações sobre como usar cartões, consulte cartões e ações de cartão.

protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionSubmitActionAsync(
  ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
{
    var response = new MessagingExtensionActionResponse
    {
        ComposeExtension = new MessagingExtensionResult
        {
            AttachmentLayout = "list",
            Type = "result",
        },
    };
    var createCardData = ((JObject)action.Data).ToObject<CreateCardData>();
var card = new HeroCard
{
     Title = createCardData.Title,
     Subtitle = createCardData.Subtitle,
     Text = createCardData.Text,
};
    var attachments = new List<MessagingExtensionAttachment>();
    attachments.Add(new MessagingExtensionAttachment
    {
        Content = card,
        ContentType = HeroCard.ContentType,
        Preview = card.ToAttachment(),
    });
    response.ComposeExtension.Attachments = attachments;
    return response;
}

Responder com outra caixa de diálogo

Pode optar por responder ao submitAction evento com uma caixa de diálogo adicional. É útil nos seguintes cenários:

  • Colete grandes quantidades de informações.
  • Altere dinamicamente a coleta de informações com base na entrada do usuário.
  • Valide as informações enviadas pelo usuário e reenvie o formulário com uma mensagem de erro se algo estiver errado.

O método de resposta é o mesmo que responder ao evento fetchTask inicial. Se você estiver usando o SDK Bot Framework os mesmos gatilhos de evento para ambas as ações de envio. Para fazer isso funcionar, você deve adicionar uma lógica que determine a resposta correta.

Resposta do bot com Cartão Adaptável

Observação

  • O pré-requisito para obter a resposta do bot com um Cartão Ajustável é que tem de adicionar o bot objeto ao manifesto da aplicação e definir o âmbito necessário para o bot. Use a mesma ID da extensão de mensagem para o bot.

  • O Outlook não suporta a resposta do bot com o Cartão Ajustável.

Você também pode responder ao submitAction inserindo uma mensagem com um Cartão Adaptável no canal com um bot. O usuário pode visualizar a mensagem antes de enviá-la. É útil em cenários em que recolhe informações dos utilizadores antes de criar uma resposta de Cartão Ajustável ou quando atualiza o cartão depois de alguém interagir com o mesmo.

O cenário a seguir mostra como o aplicativo Polly configura uma votação sem incluir as etapas de configuração na conversa do canal:

Para configurar a votação:

  1. O utilizador seleciona a extensão da mensagem para invocar a caixa de diálogo.

  2. O utilizador configura o inquérito com a caixa de diálogo.

  3. Quando o utilizador submete a caixa de diálogo, a aplicação utiliza as informações fornecidas para criar o inquérito como um Cartão Ajustável e envia-o como botMessagePreview resposta ao cliente.

  4. Em seguida, o usuário pode visualizar a mensagem cartão adaptável antes que o bot a insira no canal. Se a aplicação não for membro do canal, selecione Send para adicioná-la.

    Observação

    • Os utilizadores também podem selecionar para Edit a mensagem, que os devolve à caixa de diálogo original.
    • A interação com o Cartão Adaptável altera a mensagem antes de enviá-la.

  5. Depois de o utilizador selecionar Send, o bot publica a mensagem no canal.

Responder à ação de envio inicial

A sua caixa de diálogo tem de responder à mensagem inicial composeExtensions/submitAction com uma pré-visualização do cartão que o bot envia para o canal. O utilizador pode verificar o cartão antes de enviar e tentar instalar o bot na conversação se o bot já estiver instalado.

protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionSubmitActionAsync(
  ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
{
  dynamic createCardData = ((JObject) action.Data).ToObject(typeof(JObject));
  var response = new MessagingExtensionActionResponse
  {
    ComposeExtension = new MessagingExtensionResult
    {
      Type = "botMessagePreview",
      ActivityPreview = MessageFactory.Attachment(new Attachment
      {
        Content = new AdaptiveCard("1.0")
        {
          Body = new List<AdaptiveElement>()
          {
            new AdaptiveTextBlock() { Text = "FormField1 value was:", Size = AdaptiveTextSize.Large },
            new AdaptiveTextBlock() { Text = Data["FormField1"] as string }
          },
          Height = AdaptiveHeight.Auto,
          Actions = new List<AdaptiveAction>()
          {
            new AdaptiveSubmitAction
            {
              Type = AdaptiveSubmitAction.TypeName,
              Title = "Submit",
              Data = new JObject { { "submitLocation", "messagingExtensionFetchTask" } },
            },
          }
        },
        ContentType = AdaptiveCard.ContentType
      }) as Activity
    }
  };

  return response;
}

Os eventos de envio e edição do botMessagePreview

Sua extensão de mensagem deve responder a dois novos tipos da invocação composeExtensions/submitAction, em que value.botMessagePreviewAction = "send"e value.botMessagePreviewAction = "edit".

protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionBotMessagePreviewEditAsync(
  ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
{
  //handle the event
}

protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionBotMessagePreviewSendAsync(
  ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
{
  //handle the event
}

Responder à edição botMessagePreview

Se o usuário editar o cartão antes de enviar, selecionando Editar, você receberá uma invocação composeExtensions/submitAction com value.botMessagePreviewAction = edit. Responda ao devolver a caixa de diálogo que enviou, em resposta à invocação inicial composeExtensions/fetchTask que iniciou a interação. O utilizador pode iniciar o processo ao reintroduzir as informações originais. Utilize as informações disponíveis para atualizar a caixa de diálogo para que o utilizador não precise de preencher todas as informações do zero. Para obter mais informações sobre como responder ao evento inicial fetchTask, consulte respondendo ao evento fetchTask inicial.

Responder ao envio de botMessagePreview

Depois que o usuário selecionar Enviar, você receberá uma invocação composeExtensions/submitAction com value.botMessagePreviewAction = send. O seu serviço Web tem de criar e enviar uma mensagem com o Cartão Ajustável para a conversação e também responder à invocação.

protected override async Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionBotMessagePreviewSendAsync(
  ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
{
  var activityPreview = action.BotActivityPreview[0];
  var attachmentContent = activityPreview.Attachments[0].Content;
  var previewedCard = JsonConvert.DeserializeObject<AdaptiveCard>(attachmentContent.ToString(),
          new JsonSerializerSettings { NullValueHandling = NullValueHandling.Ignore });
  
  previewedCard.Version = "1.0";

  var responseActivity = Activity.CreateMessageActivity();
  Attachment attachment = new Attachment()
  {
    ContentType = AdaptiveCard.ContentType,
    Content = previewedCard
  };
  responseActivity.Attachments.Add(attachment);
  
  // Attribute the message to the user on whose behalf the bot is posting
  responseActivity.ChannelData = new {
    OnBehalfOf = new []
    {
      new
      {
        ItemId = 0,
        MentionType = "person",
        Mri = turnContext.Activity.From.Id,
        DisplayName = turnContext.Activity.From.Name
      }  
    }
  };
  
  await turnContext.SendActivityAsync(responseActivity);

  return new MessagingExtensionActionResponse();
}

Atribuição de usuário para mensagens de bots

Em cenários em que um bot envia mensagens em nome de um utilizador, atribuir a mensagem a esse utilizador ajuda com o envolvimento e apresentar um fluxo de interação mais natural. Esta funcionalidade permite que o bot mostre mensagens em nome de um utilizador com o nome do utilizador apresentado no cabeçalho de resposta Cartão Ajustável.

As imagens seguintes apresentam uma mensagem de Cartão Ajustável enviada por um bot. A imagem do lado esquerdo não tem atribuição de utilizador e a imagem do lado direito está com a atribuição do utilizador. A imagem com atribuição de utilizador apresenta o nome do utilizador no formato: nome de utilizador através do bot (Megan Bowen via Poll) no cabeçalho Cartão Ajustável.

Bots de atribuição de usuário

Para usar a atribuição de usuário em equipes, você deve adicionar a entidade de menção OnBehalfOf à carga de trabalho ChannelData na carga do Activity enviada ao Teams.

// Attribute the message to the user on whose behalf the bot is posting
  responseActivity.ChannelData = new {
    OnBehalfOf = new []
    {
      new
      {
        ItemId = 0,
        MentionType = "person",
        Mri = turnContext.Activity.From.Id,
        DisplayName = turnContext.Activity.From.Name
      }  
    }
  };

Detalhes do esquema de OnBehalfOf entidade

A seção a seguir é uma descrição das entidades na matriz OnBehalfOf:

Campo Tipo Descrição
itemId Inteiro Descreve a identificação do item. Seu valor deve ser 0.
mentionType Cadeia de caracteres Descreve a menção de uma "pessoa".
mri Cadeia de caracteres Identificador de recurso de mensagem (MRI) da pessoa em cujo nome a mensagem é enviada. O nome do remetente da mensagem apareceria como "<utilizador> através do nome> do <bot".
displayName Cadeia de caracteres Nome da pessoa. Usado como fallback caso a resolução de nomes não esteja disponível.

Exemplo de código

Nome do exemplo Descrição .NET Node.js Manifesto
Ação de extensão de mensagem do Teams Este exemplo mostra como definir comandos de ação, criar caixa de diálogo e responder à ação de submissão da caixa de diálogo. View View Exibir
Pré-visualização da ação da extensão de mensagem Este exemplo mostra como utilizar a pré-visualização de ações em Extensões de Mensagens com o Bot Framework v4. View View Exibir
Pesquisa de extensão de mensagem do Teams Este exemplo mostra como criar uma Extensão de Mensagem baseada em Pesquisa. Procura em pacotes NuGet e apresenta os resultados na extensão de mensagens baseada em pesquisa. View View Exibir

Próxima etapa

Definir comandos de pesquisa

Confira também