Adición de datos adjuntos multimedia a mensajes con Bot Connector APIAdd media attachments to messages with the Bot Connector API

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 (como imágenes, vídeos, audio, archivos) y tarjetas enriquecidas.For example, your bot can send media attachments (e.g., images, videos, audio, files) and rich cards. En este artículo se describe cómo agregar datos adjuntos de elementos multimedia a mensajes mediante el servicio Bot Connector.This article describes how to add media attachments to messages using the Bot Connector service.

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.

Incorporación de datos adjuntos con elementos multimediaAdd a media attachment

Para agregar datos adjuntos con elementos multimedia a un mensaje, cree un objeto Datos adjuntos, establezca la propiedad name, establezca la propiedad contentUrl en la dirección URL del archivo multimedia y establezca la propiedad contentType en el tipo de elemento multimedia adecuado (por ejemplo, imagen/png, audio/wav, vídeo/mp4).To add a media attachment to a message, create an Attachment object, set the name property, set the contentUrl property to the URL of the media file, and set the contentType property to the appropriate media type (e.g., image/png, audio/wav, video/mp4). A continuación, en el objeto Actividad que representa el mensaje, especifique el objeto Attachment dentro de la matriz attachments.Then within the Activity object that represents your message, specify your Attachment object within the attachments array.

En el ejemplo siguiente se muestra una solicitud que envía un mensaje que contiene texto y datos adjuntos con una sola imagen.The following example shows a request that sends a message containing text and a single image 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"
    },
    "text": "Here's a picture of the duck I was telling you about.",
    "attachments": [
        {
            "contentType": "image/png",
            "contentUrl": "https://www.publicdomainpictures.net/pictures/30000/t2/duck-on-a-rock.jpg",
            "name": "duck-on-a-rock.jpg"
        }
    ],
    "replyToId": "5d5cdc723"
}

En el caso de canales que admiten datos binarios en línea de una imagen, puede establecer la propiedad contentUrl del objeto Attachment en un archivo binario de base64 de la imagen (por ejemplo, datos:imagen/png;base64, iVBORw0KGgo... ).For channels that support inline binaries of an image, you can set the contentUrl property of the Attachment to a base64 binary of the image (for example, data:image/png;base64,iVBORw0KGgo…). El canal mostrará la imagen o la dirección URL de la imagen junto a la cadena de texto del mensaje.The channel will display the image or the image's URL next to the message's text string.

{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "sender's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
   },
   "recipient": {
        "id": "1234abcd",
        "name": "recipient's name"
    },
    "text": "Here's a picture of the duck I was telling you about.",
    "attachments": [
        {
            "contentType": "image/png",
            "contentUrl": "data:image/png;base64,iVBORw0KGgo…",
            "name": "duck-on-a-rock.jpg"
        }
    ],
    "replyToId": "5d5cdc723"
}

Puede adjuntar un archivo de vídeo o de audio a un mensaje siguiendo el mismo proceso descrito anteriormente para un archivo de imagen.You can attach a video file or audio file to a message by using the same process as described above for an image file. Dependiendo del canal, el vídeo y el audio pueden reproducirse en línea o se pueden mostrar como un vínculo.Depending on the channel, the video and audio may be played inline or it may be displayed as a link.

Nota

Su bot también puede recibir mensajes que contengan datos adjuntos de elementos multimedia.Your bot may also receive messages that contain media attachments. Por ejemplo, un mensaje que recibe el bot puede contener datos adjuntos si el canal permite al usuario cargar una foto para analizar o un documento para almacenar.For example, a message that your bot receives may contain an attachment if the channel enables the user to upload a photo to be analyzed or a document to be stored.

Incorporación de datos adjuntos de tarjeta de audioAdd an AudioCard attachment

Agregar datos adjuntos de AudioCard o VideoCard es lo mismo que agregar datos adjuntos de elementos multimedia.Adding an AudioCard or VideoCard attachment is the same as adding a media attachment. Por ejemplo, el siguiente código JSON muestra cómo agregar una tarjeta de audio en los datos adjuntos de elementos multimedia.For example, the following JSON shows how to add an audio card in the media attachment.

{
    "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.audio",
      "content": {
        "title": "Allegro in C Major",
        "subtitle": "Allegro Duet",
        "text": "No Image, No Buttons, Autoloop, Autostart, Sharable",
        "duration": "PT2M55S",
        "media": [
          {
            "url": "https://contoso.com/media/AllegrofromDuetinCMajor.mp3"
          }
        ],
        "shareable": true,
        "autoloop": true,
        "autostart": true,
        "value": {
            // Supplementary parameter for this card
        }
      }
    }],
    "replyToId": "5d5cdc723"
}

Una vez que el canal recibe estos datos adjuntos, comenzará a reproducirse el archivo de audio.Once the channel receives this attachment, it will start playing the audio file. Si un usuario interactúa con el audio y hace clic en el botón Pausar, por ejemplo, el canal enviará una devolución de llamada al bot con un código JSON similar al siguiente:If a user interacts with audio by clicking the Pause button, for example, the channel will send a callback to the bot with a JSON that look something like this:

{
    ...
    "type": "event",
    "name": "media/pause",
    "value": {
        "url": // URL for media
        "cardValue": {
            // Supplementary parameter for this card
        }
    }
}

El nombre del evento multimedia media/pause aparecerá en el campo activity.name.The media event name media/pause will appear in the activity.name field. Tome como referencia la tabla siguiente para obtener una lista de todos los nombres de eventos multimedia.Reference the below table for a list of all media event names.

EventoEvent DescripciónDescription
media/nextmedia/next El cliente saltó al siguiente elemento multimediaThe client skipped to the next media
media/pausemedia/pause El cliente pausó la reproducción del elemento multimediaThe client paused playing media
media/playmedia/play El cliente inició la reproducción del elemento multimediaThe client began playing media
media/previousmedia/previous El cliente saltó al elemento multimedia anteriorThe client skipped to the previous media
media/resumemedia/resume El cliente reanudó la reproducción del elemento multimediaThe client resumed playing media
media/stopmedia/stop El cliente detuvo la reproducción del elemento multimediaThe client stopped playing media

Recursos adicionalesAdditional resources