Incorporación de datos adjuntos de tarjeta enriquecciones a mensajes con Bot Connector APIAdding rich card attachments to messages with the Bot Connector API

Algunos canales permiten al bot enviar tarjetas enriquecciones a los usuarios.Some channels allow your bot to send rich cards to users. Una tarjeta enriquecte es un archivo adjunto que contiene elementos interactivos, como botones, texto, imágenes, audio, vídeo, entre otros.A rich card is an attachment that contains interactive elements, such as buttons, text, images, audio, video, and so on.

En este artículo se describe cómo crear tarjetas enriquecciones que se pueden adjuntar a un mensaje.This article describes how to create rich cards that you can attachment to a message. Vea cómo agregar datos adjuntos multimedia a mensajes para obtener instrucciones específicas sobre cómo agregar datos adjuntos a un mensaje.See how to add media attachments to messages for specific instructions on adding an attachment to a message.

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.

Para que funcione correctamente, asigne un tipo de acción a cada elemento en el que se pueda hacer clic en una tarjeta Hero.To function correctly, assign an action type to each clickable item on a hero card. Esta tabla enumera y describe los tipos de acciones disponibles y lo que debería estar en la propiedad de valor asociada.This table lists and describes the available action types and what should be in the associated value property. La messageBack acción de tarjeta tiene un significado más generalizado que las demás acciones de tarjeta.The messageBack card action has a more generalized meaning than the other card actions. Vea la sección acción de tarjeta del esquema de actividad para obtener más información acerca de messageBack y otros tipos de acciones de tarjeta.See the Card action section of the Activity schema for more information about the messageBack and other card action types.

TipoType DescripciónDescription ValorValue
llamadacall Inicia una llamada de teléfono.Initiates a phone call. Destino de una llamada telefónica con este formato: tel:123123123123.Destination for the phone call in this format: tel:123123123123.
DownloadFiledownloadFile Descarga un archivo.Downloads a file. La dirección URL del archivo que se va a descargar.The URL of the file to download.
imBackimBack Envía un mensaje al bot y publica una respuesta visible en el chat.Sends a message to the bot, and posts a visible response in the chat. Texto del mensaje para enviar.Text of the message to send.
messageBackmessageBack Representa una respuesta de texto que se va a enviar a través del sistema de chat.Represents a text response to be sent via the chat system. Valor de programación opcional que se va a incluir en los mensajes generados.An optional programmatic value to include in generated messages.
openUrlopenUrl Se abre una dirección URL en el explorador integrado.Opens a URL in the built-in browser. Dirección URL que se va a abrir.The URL to open.
playAudioplayAudio Reproduce audio.Plays audio. La dirección URL del audio que se va a reproducir.The URL of the audio to play.
playVideoplayVideo Reproduce un vídeo.Plays a video. La dirección URL del vídeo que se va a reproducir.The URL of video to play.
postBackpostBack Envía un mensaje al bot y puede no publicar una respuesta visible en el chat.Sends a message to the bot, and may not post a visible response in the chat. Texto del mensaje para enviar.Text of the message to send.
showImageshowImage Muestra una imagen.Displays an image. La dirección URL de la imagen que se va a mostrar.The URL of the image to display.
signinsignin Inicia un proceso de inicio de sesión de OAuth.Initiates an OAuth sign-in process. La dirección URL del flujo de OAuth que se va a iniciar.The URL of the OAuth flow to initiate.

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

Para agregar datos adjuntos de tarjeta enriquecciones a un mensaje:To add a rich card attachment to a message:

  1. Cree un objeto que represente el tipo de tarjeta que desea agregar al mensaje.Create an object that represents the type of card that you want to add to the message.
  2. Cree un objeto [Attachment:][]Create an Attachment object:
    • Establezca su contentType propiedad en el tipo de medio de la tarjeta.Set its contentType property to the card's media type.
    • Establezca su content propiedad en el objeto que creó para representar la tarjeta.Set its content property to the object you created to represent the card.
  3. Agregue el Attachment objeto a la attachments matriz del mensaje.Add the Attachment object to 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 un mensaje completo que contiene un único archivo adjunto de tarjeta hero.The following example shows a complete message that contains 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://www.publicdomainpictures.net/pictures/30000/t2/duck-on-a-rock.jpg",
                        "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://www.publicdomainpictures.net/pictures/30000/t2/duck-on-a-rock.jpg",
                        "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.

En el ejemplo siguiente se muestra un único objeto de datos adjuntos de tarjeta adaptable, que representa una asignación de trabajo.The following example shows a single Adaptive Card attachment object, representing a work assignment. Para enviar esto a un usuario, debe agregarlo como datos adjuntos en un mensaje.To send this to a user, you would need to add it as an attachment in a message.

{
  "$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