Respuesta a la acción de envío del cuadro de diálogo

  • Artículo

Importante

Los ejemplos de código de esta sección se basan en la versión 4.6 y versiones posteriores del SDK de Bot Framework. Si busca documentación para versiones anteriores, consulte la sección Extensiones de mensaje - SDK v3 en la carpeta Recursos de la documentación.

Este documento le guía sobre cómo responde la aplicación a los comandos de acción, como la acción de envío del cuadro de diálogo del usuario (denominado módulo de tareas en TeamsJS v1.x). Una vez que un usuario envía el cuadro de diálogo, el servicio web recibe un mensaje de composeExtensions/submitAction invocación con el identificador de comando y los valores de parámetro. La aplicación tiene cinco segundos para responder a la invocación.

Tiene las siguientes opciones:

Si la aplicación no responde en cinco segundos, el cliente de Teams vuelve a intentar la solicitud dos veces antes de enviar un mensaje de error No se puede llegar a la aplicación. Si el bot responde después del tiempo de espera, se omite la respuesta.

Nota:

  • La aplicación debe aplazar las acciones de ejecución prolongada después de que el bot responda a la solicitud de invocación. Los resultados de la acción de ejecución prolongada se pueden entregar como un mensaje.
  • La aplicación tiene cinco segundos para responder al mensaje de invocación.

Para la autenticación o configuración, una vez que el usuario completa el proceso, la invocación original se resiente para el servicio web. En la tabla siguiente se muestra qué tipos de respuestas están disponibles, en función de la ubicación commandContext de invocación de la extensión de mensaje:

Tipo de respuesta Redacción Barra de comandos Message
Respuesta de tarjeta ✔️ ✔️ ✔️
Otro cuadro de diálogo ✔️ ✔️ ✔️
Bot con tarjeta adaptable ✔️ ❌ ✔️
Sin respuesta ✔️ ✔️ ✔️

Nota:

  • Al seleccionar Action.Submit a través de tarjetas ME, envía la actividad invoke con el nombre composeExtensions, donde el valor es igual a la carga habitual.
  • Al seleccionar Action.Submit a través de la conversación, recibirá la actividad del mensaje con el nombre onCardButtonClicked, donde el valor es igual a la carga habitual.

Si la aplicación contiene un bot conversacional, instale el bot en la conversación y, a continuación, cargue el cuadro de diálogo. El bot es útil para obtener más contexto para el cuadro de diálogo. Para instalar el bot conversacional, consulte Solicitud para instalar el bot conversacional.

Evento de invocación submitAction

Los ejemplos de recepción del mensaje de invocación son los siguientes:

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

Responder con una tarjeta insertada en el área del mensaje de redacción

La manera más común de responder a la solicitud composeExtensions/submitAction es con una tarjeta insertada en el área del mensaje de redacción. El usuario envía la tarjeta a la conversación. Para obtener más información sobre el uso de tarjetas, consulte tarjetas y acciones de tarjetas.

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 con otro cuadro de diálogo

Puede seleccionar responder al submitAction evento con un cuadro de diálogo adicional. Es útil en los siguientes escenarios:

  • Recopilar grandes cantidades de información.
  • Cambiar dinámicamente la recopilación de información en función de la entrada del usuario.
  • Validar la información enviada por el usuario y volver a enviar el formulario con un mensaje de error si hay algún error.

El método de respuesta es el mismo que responder al evento inicialfetchTask. Si usa el SDK de Bot Framework, los mismos desencadenadores de eventos para ambas acciones de envío. Para que esto funcione, debe agregar la lógica que determine la respuesta correcta.

Respuesta del bot con tarjeta adaptable

Nota:

  • El requisito previo para obtener la respuesta del bot con una tarjeta adaptable es que debe agregar el bot objeto al manifiesto de la aplicación y definir el ámbito necesario para el bot. Use el mismo identificador que la extensión de mensaje para el bot.

  • Outlook no admite la respuesta del bot con la tarjeta adaptable.

También puede responder a submitAction mediante la inserción de un mensaje con una tarjeta adaptable en el canal con un bot. El usuario puede obtener una vista previa del mensaje antes de enviarlo. Resulta útil en escenarios en los que se recopila información de los usuarios antes de crear una respuesta de tarjeta adaptable o cuando se actualiza la tarjeta después de que alguien interactúe con ella.

En el siguiente escenario se muestra cómo la aplicación Polly configura un sondeo sin incluir los pasos de configuración en la conversación del canal:

Para configurar el sondeo:

  1. El usuario selecciona la extensión de mensaje para invocar el cuadro de diálogo.

  2. El usuario configura el sondeo con el cuadro de diálogo.

  3. Cuando el usuario envía el cuadro de diálogo, la aplicación usa la información proporcionada para compilar el sondeo como una tarjeta adaptable y la envía como respuesta botMessagePreview al cliente.

  4. A continuación, el usuario puede obtener una vista previa del mensaje de tarjeta adaptable antes de que el bot lo inserte en el canal. Si la aplicación no es miembro del canal, seleccione Send esta opción para agregarla.

    Nota:

    • Los usuarios también pueden seleccionar Edit el mensaje, que los devuelve al cuadro de diálogo original.
    • La interacción con la tarjeta adaptable cambia el mensaje antes de enviarlo.

  5. Una vez que el usuario selecciona Send, el bot publica el mensaje en el canal.

Respuesta a la acción de envío inicial

El cuadro de diálogo debe responder al mensaje inicial composeExtensions/submitAction con una vista previa de la tarjeta que el bot envía al canal. El usuario puede comprobar la tarjeta antes de enviar e intentar instalar el bot en la conversación si el bot ya está 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;
}

BotMessagePreview envía y edita eventos

La extensión de mensaje debe responder a dos tipos nuevos de la invocación composeExtensions/submitAction, donde value.botMessagePreviewAction = "send" y 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 a la edición botMessagePreview

Si el usuario edita la tarjeta antes de enviarla, al seleccionar Editar, recibirá una composeExtensions/submitAction invocación con value.botMessagePreviewAction = edit. Responda devolviendo el cuadro de diálogo que envió, en respuesta a la invocación inicial composeExtensions/fetchTask que inició la interacción. El usuario puede iniciar el proceso si vuelve a escribir la información original. Use la información disponible para actualizar el cuadro de diálogo de modo que el usuario no tenga que rellenar toda la información desde cero. Para obtener más información sobre cómo responder al evento inicial fetchTask, consulte Responder al evento inicialfetchTask.

Respuesta al envío de botMessagePreview

Después de que el usuario seleccione Enviar, recibirá una composeExtensions/submitAction invocación con value.botMessagePreviewAction = send. El servicio web debe crear y enviar un mensaje con la tarjeta adaptable a la conversación y también responder a la invocación.

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();
}

Atribución de usuarios para mensajes de bots

En escenarios en los que un bot envía mensajes en nombre de un usuario, atribuir el mensaje a ese usuario ayuda con la interacción y muestra un flujo de interacción más natural. Esta característica permite que el bot muestre mensajes en nombre de un usuario con el nombre del usuario mostrado en el encabezado de respuesta de la tarjeta adaptable.

En las imágenes siguientes se muestra un mensaje de tarjeta adaptable enviado por un bot. La imagen del lado izquierdo no tiene atribución de usuario y la imagen del lado derecho es con atribución de usuario. La imagen con atribución de usuario muestra el nombre del usuario en el formato: nombre de usuario a través del bot (Megan Bowen a través de sondeo) en el encabezado de tarjeta adaptable.

Bots de atribución de usuarios

Para usar la atribución de usuario en Teams, debe agregar la OnBehalfOf entidad de mención a ChannelData en Activity la carga que se envía a 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
      }  
    }
  };

Detalles del esquema de OnBehalfOf entidad

La sección siguiente es una descripción de las entidades de la matriz OnBehalfOf:

Field Tipo Descripción
itemId Entero Describe la identificación del elemento. Su valor debe ser 0.
mentionType Cadena Describe la mención de una “persona”.
mri Cadena Identificador de recurso de mensaje (MRI) de la persona en cuyo nombre se envía el mensaje. El nombre del remitente del mensaje aparecería como "<nombre de usuario> a través del <bot>".
displayName Cadena Nombre de la persona que publicó el flujo de trabajo. Se usa como reserva en la resolución de nombres de caso no está disponible.

Ejemplo de código

Ejemplo de nombre Descripción .NET Node.js Manifiesto
Acción de extensión de mensaje de Teams En este ejemplo se muestra cómo definir comandos de acción, crear cuadros de diálogo y responder a la acción de envío del cuadro de diálogo. View View Ver
Vista previa de la acción de extensión de mensaje En este ejemplo se muestra cómo usar la versión preliminar de la acción en Extensiones de mensajería mediante Bot Framework v4. View View View
Búsqueda de extensión de mensaje de Teams En este ejemplo se muestra cómo crear una extensión de mensaje basada en Búsqueda. Busca paquetes NuGet y muestra los resultados en la extensión de mensajería basada en búsquedas. View View View

Paso siguiente

Definición de comandos de búsqueda

Consulte también