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

  • Artigo

Importante

Os exemplos de código nesta seção são baseados em versões v4.6 e posteriores do SDK do Bot Framework. Se você estiver procurando documentação para versões anteriores, consulte a seção Extensões de Mensagem – v3 SDK na pasta Recursos da documentação.

Este documento orienta como seu aplicativo responde aos comandos de ação, como a caixa de diálogo do usuário (conhecida como módulo de tarefa no TeamsJS v1.x) enviar a ação. Depois que um usuário envia a caixa de diálogo, seu serviço Web recebe uma composeExtensions/submitAction mensagem de invocação com a ID de comando e os valores de parâmetro. Seu aplicativo tem cinco segundos para responder à invocação.

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

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

Observação

  • O aplicativo deve adiar qualquer ação de execução longa depois que o bot responder à solicitação de invocação. Os resultados da ação de longa duração podem ser entregues como uma mensagem.
  • Seu aplicativo 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 a seguir mostra quais tipos de respostas estão disponíveis, com base no local 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 você seleciona Action.Submit por meio de cartões ME, ele envia atividade de invocação com o nome composeExtensions, em que o valor é igual ao conteúdo usual.
  • 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 o aplicativo contiver um bot de conversa, instale o bot na conversa e 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

Você pode selecionar para responder ao submitAction evento com 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 Adaptável é que você deve adicionar o objeto ao manifesto do bot aplicativo e definir o escopo necessário para o bot. Use a mesma ID da extensão de mensagem para o bot.

  • O Outlook não dá suporte à resposta do bot com Cartão Adaptá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 você coleta informações dos usuários antes de criar uma resposta do Cartão Adaptável ou quando você atualiza o cartão depois que alguém interage com ele.

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 usuário seleciona a extensão da mensagem para invocar a caixa de diálogo.

  2. O usuário configura a sondagem com a caixa de diálogo.

  3. Quando o usuário envia a caixa de diálogo, o aplicativo usa as informações fornecidas para criar a pesquisa como um Cartão Adaptável e envia-a como uma 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 o aplicativo não for um membro do canal, selecione Send para adicioná-lo.

    Observação

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

  5. Depois que o usuário seleciona Send, o bot posta a mensagem no canal.

Responder à ação de envio inicial

Sua caixa de diálogo deve responder à mensagem inicial composeExtensions/submitAction com uma visualização do cartão que o bot envia para o canal. O usuário pode verificar o cartão antes de enviar e tentar instalar o bot na conversa 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 retornando a caixa de diálogo enviada, em resposta à invocação inicial composeExtensions/fetchTask que iniciou a interação. O usuário pode iniciar o processo reentrando as informações originais. Use as informações disponíveis para atualizar a caixa de diálogo para que o usuário não precise 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. Seu serviço Web deve criar e enviar uma mensagem com o Cartão Adaptável para a conversa 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 usuário, atribuir a mensagem a esse usuário ajuda no engajamento e exibir um fluxo de interação mais natural. Esse recurso permite que o bot mostre mensagens em nome de um usuário com o nome do usuário exibido no cabeçalho de resposta do Cartão Adaptável.

As imagens a seguir exibem uma mensagem de Cartão Adaptável enviada por um bot. A imagem do lado esquerdo está sem a atribuição do usuário e a imagem do lado direito está com a atribuição do usuário. A imagem com a atribuição do usuário exibe o nome do usuário no formato: nome de usuário via bot (Megan Bowen via Poll) no cabeçalho Cartão Adaptá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 MrI (identificador de recurso de mensagem) da pessoa em cujo nome a mensagem é enviada. O nome do remetente de mensagens seria exibido como "<usuário> por meio 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 envio de diálogo. View View Exibir
Visualização da ação de extensão de mensagem Este exemplo mostra como usar a visualização de ação em Extensões de Mensagens usando 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. Ele pesquisa pacotes NuGet e exibe os resultados na extensão de mensagens baseada em pesquisa. View View Exibir

Próxima etapa

Definir comandos de pesquisa

Confira também