Incorporación de datos adjuntos de tarjetas enriquecidas a mensajesAdd rich card attachments to messages

Los bots y los canales suelen intercambiar cadenas de texto, pero algunos canales también admiten el intercambio de datos adjuntos, lo que permite a un bot enviar mensajes más completos a los usuarios.Bots and channels typically exchange text strings but some channels also support exchanging attachments, which lets your bot send richer messages to users. Por ejemplo, el bot puede enviar datos adjuntos de elementos multimedia y tarjetas enriquecidas (como imágenes, vídeos, audio, archivos).For example, your bot can send rich cards and media attachments (e.g., images, videos, audio, files). En este artículo se describe cómo agregar datos adjuntos de tarjetas enriquecidas a mensajes mediante el servicio Bot Connector.This article describes how to add rich card attachments to messages using the Bot Connector service.

Nota

Para información sobre cómo agregar datos adjuntos con elementos multimedia a los mensajes, consulte Incorporación de datos adjuntos con elementos multimedia a mensajes.For information about how to add media attachments to messages, see Add media attachments to messages.

Tipos de tarjetas enriquecidasTypes of rich cards

Una tarjeta enriquecida consta de un título, una descripción, un vínculo e imágenes.A rich card comprises a title, description, link, and images. Un mensaje puede contener varias tarjetas enriquecidas, que se muestran en formato de lista o de carrusel.A message can contain multiple rich cards, displayed in either list format or carousel format. Bot Framework admite actualmente ocho tipos de tarjetas enriquecidas:The Bot Framework currently supports eight types of rich cards:

Tipo de tarjetaCard type DescripciónDescription
AdaptiveCardAdaptiveCard Una tarjeta personalizable que puede contener cualquier combinación de texto, voz, imágenes, botones y campos de entrada.A customizable card that can contain any combination of text, speech, images, buttons, and input fields. Consulte la compatibilidad por canal.See per-channel support.
AnimationCardAnimationCard Una tarjeta que puede reproducir archivos GIF animados o vídeos cortos.A card that can play animated GIFs or short videos.
AudioCardAudioCard Una tarjeta que se puede reproducir un archivo de audio.A card that can play an audio file.
HeroCardHeroCard Una tarjeta que normalmente contiene una sola imagen grande, uno o varios botones y texto.A card that typically contains a single large image, one or more buttons, and text.
ThumbnailCardThumbnailCard Una tarjeta que normalmente contiene una sola imagen miniatura, uno o varios botones, y texto.A card that typically contains a single thumbnail image, one or more buttons, and text.
ReceiptCardReceiptCard Una tarjeta que permite que un bot proporcione un recibo al usuario.A card that enables a bot to provide a receipt to the user. Normalmente, contiene la lista de elementos que se incluyen en el recibo, la información de impuestos y del total, y texto adicional.It typically contains the list of items to include on the receipt, tax and total information, and other text.
SignInCardSignInCard Una tarjeta que permite al bot solicitar que un usuario inicie sesión.A card that enables a bot to request that a user sign-in. Normalmente contiene texto y uno o varios botones en los que el usuario puede hacer clic para iniciar el proceso de inicio de sesión.It typically contains text and one or more buttons that the user can click to initiate the sign-in process.
VideoCardVideoCard Una tarjeta que puede reproducir vídeos.A card that can play videos.

Sugerencia

Para ver las tablas que describen las características que se admiten en cada canal, consulte el artículo Referencia de canales.For tables describing which features are supported on each channel, see the channels reference article.

Procesamiento de eventos dentro de tarjetas enriquecidasProcess events within rich cards

Para procesar eventos dentro de tarjetas enriquecidas, use los objetos CardAction para especificar qué debe ocurrir cuando el usuario hace clic en un botón o pulsa una sección de la tarjeta.To process events within rich cards, use CardAction objects to specify what should happen when the user clicks a button or taps a section of the card. Cada objeto CardAction contiene estas propiedades:Each CardAction object contains these properties:

PropiedadProperty TipoType DescripciónDescription
channelDatachannelData stringstring Datos específicos del canal asociados a esta acciónchannel-specific data associated with this action
displayTextdisplayText stringstring Texto que aparecerá en la fuente del chat si se hace clic en el botóntest to display in the chat feed if the button is clicked
texttext stringstring Texto para la accióntext for the action
typetype stringstring tipo de acción (uno de los valores especificados en la tabla siguiente)type of action (one of the values specified in the table below)
titletitle stringstring título del botóntitle of the button
imagenimage stringstring dirección URL de la imagen del botónimage URL for the button
valuevalue stringstring valor necesario para realizar el tipo de acción especificadovalue needed to perform the specified type of action

Nota

Los botones dentro de las tarjetas adaptables no se crean mediante el uso de objetos CardAction, sino mediante el esquema que definen las tarjetas adaptables.Buttons within Adaptive Cards are not created using CardAction objects, but instead using the schema that is defined by Adaptive Cards. Consulte Incorporación de una tarjeta adaptable a un mensaje para ver un ejemplo que muestra cómo agregar botones a una tarjeta adaptable.See Add an Adaptive Card to a message for an example that shows how to add buttons to an Adaptive Card.

En esta tabla se enumeran los valores válidos para la propiedad type de un objeto CardAction y se describe el contenido esperado de la propiedad value de cada tipo:This table lists the valid values for the type property of a CardAction object and describes the expected contents of the value property for each type:

typetype valuevalue
openUrlopenUrl Dirección URL que se abrirá en el explorador integradoURL to be opened in the built-in browser
imBackimBack Texto del mensaje para enviar al bot (desde el usuario que hizo clic en el botón o que pulsó la tarjeta).Text of the message to send to the bot (from the user who clicked the button or tapped the card). Este mensaje (del usuario al bot) será visible para todos los participantes de la conversación mediante la aplicación cliente que hospeda la conversación.This message (from user to bot) will be visible to all conversation participants via the client application that is hosting the conversation.
postBackpostBack Texto del mensaje para enviar al bot (desde el usuario que hizo clic en el botón o que pulsó la tarjeta).Text of the message to send to the bot (from the user who clicked the button or tapped the card). Algunas aplicaciones cliente pueden mostrar este texto en la fuente del mensaje, donde estará visible para todos los participantes de la conversación.Some client applications may display this text in the message feed, where it will be visible to all conversation participants.
llamadacall Destino de una llamada telefónica con este formato: tel:123123123123Destination for a phone call in this format: tel:123123123123
playAudioplayAudio Dirección URL del audio que se va a reproducirURL of audio to be played
playVideoplayVideo Dirección URL del vídeo que se va a reproducirURL of video to be played
showImageshowImage Dirección URL de la imagen que se va a mostrarURL of image to be displayed
DownloadFiledownloadFile Dirección URL del archivo que se va a descargarURL of file to be downloaded
signinsignin Dirección URL del flujo de OAuth que se va a iniciarURL of OAuth flow to be initiated

Incorporación de una tarjeta de imagen prominente a un mensajeAdd a Hero card to a message

Para agregar un archivo adjunto de tarjeta enriquecido a un mensaje, cree primero un objeto que corresponda al tipo de tarjeta que desee agregar al mensaje.To add a rich card attachment to a message, first create an object that corresponds to the type of card that you want to add to the message. A continuación, cree un objeto Datos adjuntos, establezca su propiedad contentType en el tipo de elemento multimedia de la tarjeta y su propiedad content como el objeto que ha creado para representar la tarjeta.Then create an Attachment object, set its contentType property to the card's media type and its content property to the object you created to represent the card. Especifique su objeto Attachment dentro de la matriz attachments del mensaje.Specify your Attachment object within the attachments array of the message.

Sugerencia

Los mensajes que contienen datos adjuntos de tarjeta enriquecida normalmente no especifican text.Messages that contain rich card attachments typically do not specify text.

Algunos canales permiten agregar varias tarjetas enriquecidas a la matriz attachments dentro de un mensaje.Some channels allow you to add multiple rich cards to the attachments array within a message. Esta funcionalidad puede ser útil en escenarios donde desee proporcionar al usuario varias opciones.This capability can be useful in scenarios where you want to provide the user with multiple options. Por ejemplo, si el bot permite a los usuarios reservar habitaciones de hotel, podría presentar al usuario una lista de tarjetas enriquecidas que muestre los tipos de habitaciones disponibles.For example, if your bot lets users book hotel rooms, it could present the user with a list of rich cards that shows the types of available rooms. Cada tarjeta podría contener una imagen y una lista de servicios correspondientes al tipo de habitación y el usuario podría seleccionar una punteando en una tarjeta o haciendo clic en un botón.Each card could contain a picture and list of amenities corresponding to the room type and the user could select a room type by tapping a card or clicking a button.

Sugerencia

Para mostrar varias tarjetas enriquecidas en formato de lista, establezca la propiedad attachmentLayout del objeto Actividad en "list" (lista).To display multiple rich cards in list format, set the Activity object's attachmentLayout property to "list". Para mostrar varias tarjetas enriquecidas en formato de carrusel, establezca la propiedad attachmentLayout del objeto Activity en "carousel" (carrusel).To display multiple rich cards in carousel format, set the Activity object's attachmentLayout property to "carousel". Si el canal no admite el formato de carrusel, mostrará las tarjetas enriquecidas en el formato de lista, incluso si la propiedad attachmentLayout especifica "carousel" (carrusel).If the channel does not support carousel format, it will display the rich cards in list format, even if the attachmentLayout property specifies "carousel".

En el ejemplo siguiente se muestra una solicitud que envía un mensaje que contiene datos adjuntos con una sola tarjeta de imagen prominente.The following example shows a request that sends a message containing a single Hero card attachment. En la solicitud del ejemplo, https://smba.trafficmanager.net/apis representa el URI base; el URI base para solicitudes que su bot emita puede ser distinto.In this example request, https://smba.trafficmanager.net/apis represents the base URI; the base URI for requests that your bot issues may be different. Para obtener más información sobre cómo establecer el URI base, consulte API Reference (Referencia de la API).For details about setting the base URI, see API Reference.

POST https://smba.trafficmanager.net/apis/v3/conversations/abcd1234/activities/5d5cdc723
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "sender's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
    },
    "recipient": {
        "id": "1234abcd",
        "name": "recipient's name"
    },
    "attachments": [
        {
            "contentType": "application/vnd.microsoft.card.hero",
            "content": {
                "title": "title goes here",
                "subtitle": "subtitle goes here",
                "text": "descriptive text goes here",
                "images": [
                    {
                        "url": "https://aka.ms/DuckOnARock",
                        "alt": "picture of a duck",
                        "tap": {
                            "type": "playAudio",
                            "value": "url to an audio track of a duck call goes here"
                        }
                    }
                ],
                "buttons": [
                    {
                        "type": "playAudio",
                        "title": "Duck Call",
                        "value": "url to an audio track of a duck call goes here"
                    },
                    {
                        "type": "openUrl",
                        "title": "Watch Video",
                        "image": "https://aka.ms/DuckOnARock",
                        "value": "url goes here of the duck in flight"
                    }
                ]
            }
        }
    ],
    "replyToId": "5d5cdc723"
}

Incorporación de una tarjeta adaptable a un mensajeAdd an Adaptive card to a message

Una tarjeta adaptable puede contener cualquier combinación de texto, voz, imágenes, botones y campos de entrada.The Adaptive Card can contain any combination of text, speech, images, buttons, and input fields. Las tarjetas adaptables se crean con el formato JSON especificado en Adaptive Cards (Tarjetas adaptables), que proporciona control total sobre el contenido y el formato de la tarjeta.Adaptive Cards are created using the JSON format specified in Adaptive Cards, which gives you full control over card content and format.

Use la información del sitio Adaptive Cards (Tarjetas adaptables) a fin de comprender el esquema de la tarjeta adaptable, explorar los elementos de la tarjeta adaptable y ver ejemplos de JSON que puede usar para crear tarjetas de diferente composición y complejidad.Leverage the information within the Adaptive Cards site to understand Adaptive Card schema, explore Adaptive Card elements, and see JSON samples that can be used to create cards of varying composition and complexity. Además, puede usar el visualizador interactivo para diseñar cargas útiles de la tarjeta adaptable y obtener una vista previa de la salida de la tarjeta.Additionally, you can use the Interactive Visualizer to design Adaptive Card payloads and preview card output. El ejemplo siguiente es una tarjeta adaptable única para una asignación de trabajos.The following example is a single Adaptive Card for a work assignment.

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "Container",
      "items": [
        {
          "type": "TextBlock",
          "text": "Publish Adaptive Card schema",
          "weight": "bolder",
          "size": "medium"
        },
        {
          "type": "ColumnSet",
          "columns": [
            {
              "type": "Column",
              "width": "auto",
              "items": [
                {
                  "type": "Image",
                  "url": "https://pbs.twimg.com/profile_images/3647943215/d7f12830b3c17a5a9e4afcc370e3a37e_400x400.jpeg",
                  "size": "small",
                  "style": "person"
                }
              ]
            },
            {
              "type": "Column",
              "width": "stretch",
              "items": [
                {
                  "type": "TextBlock",
                  "text": "Matt Hidinger",
                  "weight": "bolder",
                  "wrap": true
                },
                {
                  "type": "TextBlock",
                  "spacing": "none",
                  "text": "Created {{DATE(2017-02-14T06:08:39Z, SHORT)}}",
                  "isSubtle": true,
                  "wrap": true
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "type": "Container",
      "items": [
        {
          "type": "TextBlock",
          "text": "Now that we have defined the main rules and features of the format, we need to produce a schema and publish it to GitHub. The schema will be the starting point of our reference documentation.",
          "wrap": true
        },
        {
          "type": "FactSet",
          "facts": [
            {
              "title": "Board:",
              "value": "Adaptive Card"
            },
            {
              "title": "List:",
              "value": "Backlog"
            },
            {
              "title": "Assigned to:",
              "value": "Matt Hidinger"
            },
            {
              "title": "Due date:",
              "value": "Not set"
            }
          ]
        }
      ]
    }
  ],
  "actions": [
    {
      "type": "Action.ShowCard",
      "title": "Comment",
      "card": {
        "type": "AdaptiveCard",
        "body": [
          {
            "type": "Input.Text",
            "id": "comment",
            "isMultiline": true,
            "placeholder": "Enter your comment"
          }
        ],
        "actions": [
          {
            "type": "Action.Submit",
            "title": "OK"
          }
        ]
      }
    },
    {
      "type": "Action.OpenUrl",
      "title": "View",
      "url": "https://adaptivecards.io"
    }
  ]
}

La tarjeta resultante contiene un título, información sobre quién creó la tarjeta (su nombre y avatar), cuándo se creó la tarjeta, una descripción de las asignaciones de trabajos e información relacionada con la asignación.The resulting card contains a title, information about who created the card (their name and avatar), when the card was created, a description of the work assignments, and information related to the assignment. También hay botones en los que se puede hacer clic para realizar un comentario sobre la asignación de trabajos o para verla:There are also buttons which can be clicked to either comment on the work assignment or view it:

Recordatorio del calendario de tarjeta adaptable

Recursos adicionalesAdditional resources