Adición de datos adjuntos multimedia a mensajes con 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. Por ejemplo, el bot puede enviar datos adjuntos multimedia (como imágenes, vídeos, audio, archivos) y tarjetas enriquecidas. En este artículo se describe cómo agregar datos adjuntos de elementos multimedia a mensajes mediante el servicio Bot Connector.
Sugerencia
Para obtener información sobre qué características se admiten en cada canal, consulte el artículo de referencia de canales .
Incorporación de datos adjuntos con elementos multimedia
Para agregar datos adjuntos multimedia a un mensaje, cree un objeto Attachment , establezca la name propiedad, establezca la contentUrl propiedad en la dirección URL del archivo multimedia y establezca la contentType propiedad en el tipo de medio adecuado (como image/jpg, audio/wav, video/mp4). A continuación, en el objeto Actividad que representa el mensaje, especifique el objeto Attachment dentro de la matriz attachments.
En el ejemplo siguiente se muestra una solicitud que envía un mensaje que contiene texto y datos adjuntos con una sola imagen. En la solicitud del ejemplo, https://smba.trafficmanager.net/teams representa el URI base; el URI base para solicitudes que su bot emita puede ser distinto. Para obtener más información sobre cómo establecer el URI base, consulte API Reference (Referencia de la API).
POST https://smba.trafficmanager.net/teams/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/jpg",
"contentUrl": "https://www.publicdomainpictures.net/pictures/30000/t2/duck-on-a-rock.jpg",
"name": "duck-on-a-rock.jpg"
}
],
"replyToId": "5d5cdc723"
}
Para los canales que admiten archivos binarios insertados de una imagen, puede establecer la contentUrl propiedad de en Attachment un binario base64 de la imagen (por ejemplo, data:image/jpg; base64,iVBORw0KGgo...). El canal mostrará la imagen o la dirección URL de la imagen junto a la cadena de texto del mensaje.
{
"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/jpg",
"contentUrl": "data:image/jpg;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. Dependiendo del canal, el vídeo y el audio pueden reproducirse en línea o se pueden mostrar como un vínculo.
Nota:
Su bot también puede recibir mensajes que contengan datos adjuntos de elementos multimedia. 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.
Incorporación de datos adjuntos de tarjeta de audio
Agregar datos adjuntos de AudioCard o VideoCard es lo mismo que agregar datos adjuntos de elementos multimedia. Por ejemplo, el siguiente código JSON muestra cómo agregar una tarjeta de audio en los datos adjuntos de elementos multimedia.
{
"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. Si un usuario interactúa con audio seleccionando Pausar, por ejemplo, el canal enviará una devolución de llamada al bot con un JSON similar al siguiente:
{
...
"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. Tome como referencia la tabla siguiente para obtener una lista de todos los nombres de eventos multimedia.
| Evento | Descripción |
|---|---|
| media/next | El cliente saltó al siguiente elemento multimedia |
| media/pause | El cliente pausó la reproducción del elemento multimedia |
| media/play | El cliente inició la reproducción del elemento multimedia |
| media/previous | El cliente saltó al elemento multimedia anterior |
| media/resume | El cliente reanudó la reproducción del elemento multimedia |
| media/stop | El cliente detuvo la reproducción del elemento multimedia |