Compartir a través de


Referencia de API para el servicio Bot Framework Connector

Nota:

La API de REST no es equivalente al SDK. La API de REST se proporciona para permitir la comunicación de REST estándar; no obstante, el método preferido para interactuar con Bot Framework es el SDK.

En Bot Framework, el servicio Bot Connector permite que el bot intercambie mensajes con los usuarios en los canales configurados en el portal de Bot Framework. El servicio usa los estándares del sector REST y JSON sobre HTTPS.

URI base

Cuando un usuario envía un mensaje al bot, la solicitud entrante contiene un objeto Actividad con una propiedad serviceUrl que especifica el punto de conexión al que el bot debe enviar su respuesta. Para acceder al servicio Bot Connector, use el valor serviceUrl como el identificador URI de base para las solicitudes de API.

Cuando aún no tenga una dirección URL de servicio para el canal, use https://smba.trafficmanager.net/teams/ como dirección URL del servicio. Para obtener más información, vea cómo crear una conversación y un mensaje proactivo en Teams.

Por ejemplo, suponga que su bot recibe la siguiente actividad cuando el usuario envía un mensaje al bot.

{
    "type": "message",
    "id": "bf3cc9a2f5de...",
    "timestamp": "2016-10-19T20:17:52.2891902Z",
    "serviceUrl": "https://smba.trafficmanager.net/teams/",
    "channelId": "channel's name/id",
    "from": {
        "id": "1234abcd",
        "name": "user's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
    },
    "recipient": {
        "id": "12345678",
        "name": "bot's name"
    },
    "text": "Haircut on Saturday"
}

La propiedad serviceUrl del mensaje del usuario indica que el bot debe enviar su respuesta al punto de conexión https://smba.trafficmanager.net/teams/. La dirección URL del servicio será el URI base para las solicitudes posteriores que emite el bot en el contexto de esta conversación. Si el bot necesita enviar un mensaje automático al usuario, asegúrese de guardar el valor de serviceUrl.

En el ejemplo siguiente se muestra la solicitud que el bot envía para responder al mensaje del usuario.

POST https://smba.trafficmanager.net/teams/v3/conversations/abcd1234/activities/bf3cc9a2f5de...
Authorization: Bearer eyJhbGciOiJIUzI1Ni...
Content-Type: application/json
{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "bot's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
    },
   "recipient": {
        "id": "1234abcd",
        "name": "user's name"
    },
    "text": "I have several times available on Saturday!",
    "replyToId": "bf3cc9a2f5de..."
}

Encabezados

Encabezados de solicitud

Además de los encabezados de solicitud HTTP estándares, todas las solicitudes de API que envíe deben incluir un encabezado Authorization que especifique un token de acceso para autenticar el bot. Especifique el encabezado Authorization con este formato:

Authorization: Bearer ACCESS_TOKEN

Para consultar información sobre cómo obtener un token de acceso para el bot, vea Authenticate requests from your bot to the Bot Connector service (Autenticación de solicitudes del bot en el servicio Bot Connector).

Encabezados de respuesta

Además de los encabezados de respuesta HTTP estándares, cada respuesta contendrá un encabezado X-Correlating-OperationId. El valor de este encabezado es un identificador que corresponde a la entrada de registro de Bot Framework que contiene detalles acerca de la solicitud. Cuando reciba una respuesta de error, debe capturar el valor de este encabezado. Si no puede resolver el problema de forma independiente, incluya este valor en la información que proporcione al equipo de soporte técnico al informar del problema.

Códigos de estado HTTP

El código de estado HTTP que se devuelve con cada respuesta indica el resultado de la solicitud correspondiente.

Nota:

En la tabla siguiente se describen algunos de los códigos de estado HTTP más comunes. El canal genera algunos errores. Para obtener más información, es posible que tenga que leer la documentación para desarrolladores del canal.

Código de estado HTTP Significado
200 La solicitud finalizó correctamente.
201 La solicitud finalizó correctamente.
202 Se aceptó la solicitud para su procesamiento.
204 La solicitud se realizó correctamente, pero no se devolvió ningún contenido.
400 La solicitud tenía formato incorrecto o era incorrecta por otro motivo.
401 El bot aún no está autenticado.
403 El bot no tiene la autorización para llevar a cabo la operación solicitada.
404 No se encontró el recurso solicitado.
405 Este canal no admite la operación solicitada.
500 Se ha producido un error del servidor interno.
503 El servicio no está disponible temporalmente.

Errores

Cualquier respuesta que especifique un código de estado HTTP en el rango de 4xx o 5xx incluirá un objeto ErrorResponse en el cuerpo de la respuesta que proporciona información sobre el error. Si recibe una respuesta de error en el rango de 4xx, inspeccione el objeto ErrorResponse para identificar la causa del error y resolver el problema antes de volver a enviar la solicitud.

Operaciones con conversaciones

Use estas operaciones para crear conversaciones, enviar mensajes (actividades) y administrar el contenido de las conversaciones.

Importante

No todos los canales admiten todos los puntos de conexión. Sin embargo, todos los canales deben admitir la respuesta al punto de conexión de actividad.

Por ejemplo, solo Direct Line y Chat en web admiten el punto de conexión de obtener conversaciones.

Operación Descripción
Crear conversación Crea una conversación.
Actividad de eliminación Elimina una actividad existente.
Eliminar miembro de la conversación Quita un miembro de una conversación.
Obtener miembros de la actividad Obtiene los miembros de la actividad especificada dentro de la conversación especificada.
Obtener miembro de la conversación Obtiene detalles sobre un miembro de una conversación.
Obtener miembros de la conversación Obtiene los miembros de la conversación especificada.
Obtener los miembros de la conversación paginados Obtiene los miembros de la conversación especificada una página a la vez.
Obtener conversaciones Obtiene una lista de las conversaciones en las que ha participado el bot.
Responder a actividad Envía una actividad (mensaje) a la conversación especificada, como una respuesta a la actividad especificada.
Enviar historial de la conversación Carga una transcripción de actividades pasadas a la conversación.
Enviar a conversación Envía una actividad (mensaje) al final de la conversación especificada.
Actualizar actividad Actualiza una actividad existente.
Cargar datos adjuntos al canal Carga un archivo adjunto directamente al almacenamiento de blobs de un canal.

Creación de conversación

Crea una conversación.

POST /v3/conversations
Contenido Descripción
Cuerpo de la solicitud Un objeto ConversationParameters
Devuelve Un objeto ConversationResourceResponse

Actividad de eliminación

Algunos canales le permiten eliminar una actividad existente. Si se realiza correctamente, esta operación elimina la actividad especificada de la conversación establecida.

DELETE /v3/conversations/{conversationId}/activities/{activityId}
Contenido Descripción
Cuerpo de la solicitud N/D
Devuelve Un código de estado HTTP que indica el resultado de la operación. No se especifica nada en el cuerpo de la respuesta.

Eliminar miembro de la conversación

Quita un miembro de una conversación. Si ese miembro era el último miembro de la conversación, también se eliminará la conversación.

DELETE /v3/conversations/{conversationId}/members/{memberId}
Contenido Descripción
Cuerpo de la solicitud N/D
Devuelve Un código de estado HTTP que indica el resultado de la operación. No se especifica nada en el cuerpo de la respuesta.

Obtener miembros de la actividad

Obtiene los miembros de la actividad especificada dentro de la conversación especificada.

GET /v3/conversations/{conversationId}/activities/{activityId}/members
Contenido Descripción
Cuerpo de la solicitud N/D
Devuelve Una matriz de objetos ChannelAccount

Obtener conversaciones

Obtiene una lista de las conversaciones en las que ha participado el bot.

GET /v3/conversations?continuationToken={continuationToken}
Contenido Descripción
Cuerpo de la solicitud N/D
Devuelve Un objeto ConversationsResult

Obtener miembro de la conversación

Obtiene detalles sobre un miembro específico de una determinada conversación.

GET /v3/conversations/{conversationId}/members/{memberId}
Contenido Descripción
Cuerpo de la solicitud N/D
Devuelve Objeto ChannelAccount para el miembro.

Obtener miembros de la conversación

Obtiene los miembros de la conversación especificada.

GET /v3/conversations/{conversationId}/members
Contenido Descripción
Cuerpo de la solicitud N/D
Devuelve Matriz de objetos ChannelAccount de los miembros de la conversación.

Obtener los miembros de la conversación paginados

Obtiene los miembros de la conversación especificada una página a la vez.

GET /v3/conversations/{conversationId}/pagedmembers?pageSize={pageSize}&continuationToken={continuationToken}
Contenido Descripción
Cuerpo de la solicitud N/D
Devuelve Un objeto PagedMembersResult

Responder a actividad

Envía una actividad (mensaje) a la conversación especificada, como una respuesta a la actividad especificada. La actividad se agregará como respuesta a otra actividad, si lo admite el canal. Si el canal no admite respuestas anidadas, esta operación se comporta como Enviar a conversación.

POST /v3/conversations/{conversationId}/activities/{activityId}
Contenido Descripción
Cuerpo de la solicitud Un objeto Activity
Devuelve Un objeto ResourceResponse

Envío de historial de la conversación

Carga una transcripción de actividades pasadas a la conversación para que el cliente pueda representarlas.

POST /v3/conversations/{conversationId}/activities/history
Contenido Descripción
Cuerpo de la solicitud Un objeto Transcript.
Devuelve Un objeto ResourceResponse.

Enviar a conversación

Envía una actividad (mensaje) a la conversación especificada. La actividad se anexará al final de la conversación según la marca de tiempo o la semántica del canal. Para responder a un mensaje específico dentro de la conversación, en su lugar, use Responder a actividad.

POST /v3/conversations/{conversationId}/activities
Contenido Descripción
Cuerpo de la solicitud Un objeto Activity
Devuelve Un objeto ResourceResponse

Actualizar actividad

Algunos canales le permiten modificar una actividad existente para reflejar el nuevo estado de una conversación de bot. Por ejemplo, puede quitar los botones de un mensaje de la conversación después de que el usuario haya hecho clic en uno de los botones. Si se realiza correctamente, esta operación actualiza la actividad especificada dentro de la conversación establecida.

PUT /v3/conversations/{conversationId}/activities/{activityId}
Contenido Descripción
Cuerpo de la solicitud Un objeto Activity
Devuelve Un objeto ResourceResponse

Cargar datos adjuntos al canal

Carga un archivo adjunto para la conversación especificada directamente en el almacenamiento de blobs de un canal. Esto le permite almacenar datos en un almacén compatible.

POST /v3/conversations/{conversationId}/attachments
Contenido Descripción
Cuerpo de la solicitud Un objeto AttachmentData.
Devuelve Un objeto ResourceResponse. La propiedad id especifica el identificador de datos adjuntos que se puede usar con las operaciones Obtener información de datos adjuntos y Obtener datos adjuntos.

Operaciones con datos adjuntos

Utilice estas operaciones para recuperar información sobre los datos adjuntos y los datos binarios para el propio archivo.

Operación Descripción
Obtener información de datos adjuntos Obtiene información sobre los datos adjuntos especificados, incluido el nombre de archivo, el tipo de archivo y las vistas disponibles (p. ej., original o miniatura).
Obtener datos adjuntos Obtiene la vista especificada de los datos adjuntos determinados como contenido binario.

Obtención de información de datos adjuntos

Obtiene información sobre los datos adjuntos especificados, incluido el nombre de archivo, el tipo y las vistas disponibles (p. ej., original o miniatura).

GET /v3/attachments/{attachmentId}
Contenido Descripción
Cuerpo de la solicitud N/D
Devuelve Un objeto AttachmentInfo

Obtener datos adjuntos

Obtiene la vista especificada de los datos adjuntos determinados como contenido binario.

GET /v3/attachments/{attachmentId}/views/{viewId}
Contenido Descripción
Cuerpo de la solicitud N/D
Devuelve Contenido binario que representa la vista especificada de los datos adjuntos establecidos

Operaciones de estado (en desuso)

El servicio de estado de Microsoft bot Framework se retirará a partir del 30 de marzo de 2018. Anteriormente, los bots creados en Servicio de Bot de Azure AI o en el SDK Bot Builder tenían una conexión predeterminada con este servicio hospedado por Microsoft para almacenar los datos de estado del bot. Los bots se deberán actualizar para usar su propio almacenamiento del estado.

Operación Descripción
Set User Data Almacena datos de estado de un usuario específico en un canal.
Set Conversation Data Almacena datos de estado de una conversación específica en un canal.
Set Private Conversation Data Almacena datos de estado de un usuario específico en el contexto de una conversación determinada en un canal.
Get User Data Recupera datos de estado que previamente se almacenaron para un usuario específico de todas las conversaciones en un canal.
Get Conversation Data Recupera datos de estado que previamente se almacenaron para una conversación específica en un canal.
Get Private Conversation Data Recupera datos de estado que previamente se almacenaron para un usuario específico en el contexto de una conversación determinada en un canal.
Delete State For User Elimina los datos de estado que se han almacenado previamente para un usuario.

Esquema

El esquema de Bot Framework define los objetos y las propiedades que puede usar el bot para comunicarse con un usuario.

Object Descripción
Objeto Activity Define un mensaje que se intercambia entre el bot y el usuario.
Objeto AnimationCard Define una tarjeta que puede reproducir archivos GIF animados o vídeos cortos.
Objeto Attachment Define información adicional que se va a incluir en el mensaje. Los datos adjuntos pueden ser un archivo multimedia (por ejemplo, audio, vídeo, imagen o archivo) o una tarjeta enriquecida.
Objeto AttachmentData Describe los datos adjuntos.
Objeto AttachmentInfo Describe los datos adjuntos.
Objeto AttachmentView Define un objeto que representa una vista disponible para los datos adjuntos.
Objeto AudioCard Define una tarjeta que puede reproducir un archivo de audio.
Objeto CardAction Define una acción que se va a realizar.
Objeto CardImage Define una imagen para mostrarla en una tarjeta.
Objeto ChannelAccount Define un bot o cuenta de usuario en el canal.
Objeto ConversationAccount Define una conversación en un canal.
Objeto ConversationMembers Define los miembros de una conversación.
Objeto ConversationParameters Define los parámetros para crear una conversación.
Objeto ConversationReference Define un punto concreto de una conversación.
Objeto ConversationResourceResponse Define una respuesta para Crear conversación.
Objeto ConversationsResult Define el resultado de una llamada a Obtener conversaciones.
Objeto Entity Define un objeto entidad.
Objeto Error Define un error.
Objeto ErrorResponse Define una respuesta de la API HTTP.
Objeto Fact Define un par clave-valor que contiene un hecho.
Objeto Geocoordinates Define una ubicación geográfica mediante las coordenadas del sistema geodésico mundial (WSG84).
Objeto HeroCard Define una tarjeta con una imagen grande, título, texto y botones de acción.
Objeto InnerHttpError Objeto que representa un error HTTP interno.
Objeto MediaEventValue Parámetros complementarios para eventos multimedia.
Objeto MediaUrl Define la dirección URL al origen de un archivo multimedia.
Objeto Mention Define un usuario o un bot que se mencionó en la conversación.
Objeto MessageReaction Define una reacción a un mensaje.
Objeto PagedMembersResult Página de miembros que devuelve la operación Obtener los miembros de la conversación paginados.
Objeto Place Define un lugar mencionado en la conversación.
Objeto ReceiptCard Define una tarjeta que contiene una recepción de una compra.
Objeto ReceiptItem Define un elemento de línea dentro de una confirmación.
Objeto ResourceResponse Define un recurso.
Objeto SemanticAction Define una referencia a una acción mediante programación.
Objeto SignInCard Define una tarjeta que permite a un usuario iniciar sesión en un servicio.
Objeto SuggestedActions Define las opciones que puede elegir un usuario.
Objeto TextHighlight Hace referencia a una subcadena de contenido dentro de otro campo.
Objeto ThumbnailCard Define una tarjeta con una imagen en miniatura, título, texto y botones de acción.
Objeto ThumbnailUrl Define la dirección URL al origen de una imagen.
Objeto Transcript Una colección de actividades que se cargará mediante Enviar historial de la conversación.
Objeto VideoCard Define una tarjeta que puede reproducir vídeos.

Objeto Activity

Define un mensaje que se intercambia entre el bot y el usuario.

Propiedad Tipo Descripción
action Cadena La acción que se va a aplicar o que se aplicó. Use la propiedad type para determinar el contexto de la acción. Por ejemplo, si type es contactRelationUpdate, el valor de la propiedad action sería add si el usuario agregó el bot a su lista de contactos, o remove si quitó el bot de su lista de contactos.
attachmentLayout Cadena Diseño de los datos adjuntos de la tarjeta enriquecida que el mensaje incluye. Uno de estos valores: carousel, list. Para más información sobre los datos adjuntos de tarjetas enriquecidas, vea Incorporación de datos adjuntos de tarjetas enriquecidas a mensajes.
attachments Attachment[] Matriz de objetos Attachment que define información adicional que se va a incluir en el mensaje. Cada dato adjunto puede ser un archivo (por ejemplo, audio, vídeo o imagen) o una tarjeta enriquecida.
callerId Cadena Una cadena que contiene un IRI que identifica al autor de la llamada de un bot. Este campo no está pensado para transmitirse a través de la conexión, sino que los bots y los clientes lo rellenan basándose en datos comprobables criptográficamente que confirman la identidad de los autores de las llamadas (por ejemplo, tokens).
channelData Object Objeto que incluye contenido específico de canal. Algunos canales proporcionan características que requieren información adicional que no se puede representar mediante el esquema de datos adjuntos. Para esos casos, establezca esta propiedad en el contenido específico de canal tal como se define en la documentación del canal. Para más información, vea Implementación de una funcionalidad específica de canal.
channelId Cadena Identificador que distingue de manera única el canal. Se establece mediante el canal.
code Cadena Código que indica por qué la conversación ha finalizado.
conversation ConversationAccount Un objeto ConversationAccount que define la conversación a la que pertenece la actividad.
deliveryMode Cadena Una sugerencia de entrega para indicar al destinatario rutas de entrega alternativas para la actividad. Uno de estos valores: normal, notification (notificación).
entities object[] Matriz de objetos que representa las entidades que se han mencionado en el mensaje. Los objetos de esta matriz pueden ser cualquier objeto Schema.org. Por ejemplo, la matriz puede incluir objetos Mention que identifican a alguien a quien se ha mencionado en la conversación y objetos Place que identifican un lugar mencionado en la conversación.
expiration Cadena La hora en que la actividad debería considerarse "expirada" y no debería presentarse al destinatario.
from ChannelAccount Un objeto ChannelAccount que especifica el remitente del mensaje.
historyDisclosed Booleano Marca que indica si se revela o no el historial. El valor predeterminado es Falso.
id Cadena Identificador que distingue de manera única la actividad en el canal.
importance Cadena Define la importancia de una actividad. Uno de estos valores: low (baja), normal, high (alta).
inputHint Cadena Valor que indica si el bot acepta, espera o ignora la entrada del usuario después de que el mensaje se haya entregado al cliente. Uno de estos valores: acceptingInput, expectingInput, ignoringInput.
label Cadena Una etiqueta descriptiva para la actividad.
listenFor String[] Lista de frases y referencias que deben escuchar los sistemas de preparación para la voz y el idioma.
locale Cadena Configuración regional del idioma que se debe usar para mostrar el texto del mensaje, en el formato <language>-<country>. El canal utiliza esta propiedad para indicar el idioma del usuario, para que su bot pueda especificar las cadenas para mostrar en ese idioma. El valor predeterminado es en-US.
localTimestamp Cadena Fecha y hora en que se envió el mensaje en la zona horaria local, expresada en el formato ISO-8601.
localTimezone Cadena Contiene el nombre de la zona horaria local del mensaje, expresado en el formato de base de datos de zona horaria de IANA. Por ejemplo, America/Los_Angeles.
membersAdded ChannelAccount[] Matriz de objetos ChannelAccount que representa la lista de usuarios que se unieron a la conversación. Presente solo si la actividad type es "conversationUpdate" y si los usuarios se unieron a la conversación.
membersRemoved ChannelAccount[] Matriz de objetos ChannelAccount que representa la lista de usuarios que abandonaron la conversación. Presente solo si la actividad type es "conversationUpdate" y si los usuarios abandonaron la conversación.
name Cadena Nombre de la operación para invocar o el nombre del evento.
reactionsAdded MessageReaction[] Colección de reacciones agregada a la conversación.
reactionsRemoved MessageReaction[] Colección de reacciones eliminada de la conversación.
recipient ChannelAccount Un objeto ChannelAccount que especifica el destinatario del mensaje.
relatesTo ConversationReference Un objeto ConversationReference que define un punto concreto en una conversación.
replyToId Cadena Identificador del mensaje al que responde este mensaje. Para responder a un mensaje que el usuario envía, establezca esta propiedad con el identificador del mensaje del usuario. No todos los canales admiten respuestas encadenadas. En estos casos, el canal ignorará esta propiedad y usará la semántica ordenada por tiempo (marca de tiempo) para anexar el mensaje a la conversación.
semanticAction SemanticAction Un objeto SemanticAction que representa una referencia a una acción mediante programación.
serviceUrl Cadena Dirección URL que especifica el punto de conexión de servicio del canal. Se establece mediante el canal.
speak Cadena Texto que pronuncia el bot en un canal habilitado para voz. Para controlar diversas características de voz del bot como voz, velocidad, volumen, pronunciación y tono, especifique esta propiedad con el formato de lenguaje de marcado de síntesis de voz (SSML).
suggestedActions SuggestedActions Un objeto SuggestedActions que define las opciones entre las que el usuario puede elegir.
summary Cadena Resumen de la información que contiene el mensaje. Por ejemplo, en un mensaje que se envía en un canal de correo electrónico, esta propiedad puede especificar los 50 primeros caracteres del mensaje de correo electrónico.
texto Cadena Texto del mensaje que se envía del usuario al bot o del bot al usuario. Consulte la documentación del canal para conocer los límites impuestos en el contenido de esta propiedad.
textFormat Cadena Formato del texto del mensaje. Uno de estos valores: markdown, plain, xml. Para más información sobre el formato del texto, vea Creación de mensajes.
textHighlights TextHighlight[] Colección de fragmentos de texto que se resaltará si la actividad contiene un valor replyToId.
timestamp Cadena Fecha y hora en que se envió el mensaje en la zona horaria UTC, expresada en el formato ISO-8601.
topicName Cadena Tema de la conversación a la que pertenece la actividad.
type String Tipo de actividad. Uno de estos valores: message, contactRelationUpdate, conversationUpdate, typing, endOfConversation, event, invoke, deleteUserData, messageUpdate, messageDelete, installationUpdate, messageReaction, suggestion, trace, handoff. Para obtener detalles sobre los tipos de actividad, vea Introducción a las actividades.
value Object Valor de final abierto.
valueType Cadena Tipo del objeto de valor de la actividad.

Volver a la tabla de esquema

Objeto AnimationCard

Define una tarjeta que puede reproducir archivos GIF animados o vídeos cortos.

Propiedad Tipo Descripción
aspect Booleano Relación de aspecto del marcador de miniatura o medio. Los valores permitidos son "16:9" y "4:3".
autoloop Booleano Marca que indica si se debe reproducir la lista de archivos GIF animados cuando finaliza la última. Establezca esta propiedad en true para reproducir el archivo animado automáticamente; de lo contrario, establézcala en false. El valor predeterminado es true.
autostart Booleano Marca que indica si se debe reproducir automáticamente el archivo de animación cuando se muestra la tarjeta. Establezca esta propiedad en true para reproducir el archivo animado automáticamente; de lo contrario, establézcala en false. El valor predeterminado es true.
buttons CardAction[] Matriz de objetos CardAction que permite al usuario realizar una o varias acciones. El canal determina el número de botones que se pueden especificar.
duration Cadena La longitud del contenido multimedia, en el formato de duración ISO 8601.
image ThumbnailUrl Un objeto ThumbnailUrl que especifica la imagen que se mostrará en la tarjeta.
media MediaUrl[] Matriz de objetos MediaUrl. Cuando este campo contiene más de una dirección URL, cada dirección URL es un formato alternativo del mismo contenido.
shareable Booleano Marca que indica si la animación puede compartirse con otros usuarios. Establezca esta propiedad en true si la animación puede compartirse; de lo contrario, en false. El valor predeterminado es true.
subtitle Cadena Subtítulo que se mostrará debajo del título de la tarjeta.
texto Cadena Descripción o mensaje para mostrar debajo del título o subtítulo de la tarjeta.
title Cadena Título de la tarjeta.
value Object Parámetro complementario de esta tarjeta.

Volver a la tabla de esquema

Objeto Attachment

Define información adicional que se va a incluir en el mensaje. Los datos adjuntos pueden ser archivos (como imágenes, audio o vídeo) o una tarjeta enriquecida.

Propiedad Tipo Descripción
content Object Contenido de los datos adjuntos. Si los datos adjuntos son una tarjeta enriquecida, establezca esta propiedad en el objeto de tarjeta enriquecida. Esta propiedad y la propiedad contentUrl son mutuamente excluyentes.
contentType Cadena Tipo de elemento multimedia del contenido de los datos adjuntos. Para los archivos multimedia, establezca esta propiedad en los tipos de elementos multimedia conocidos como image/png, audio/wav y video/mp4. Para tarjetas enriquecidas, establezca esta propiedad en uno de estos tipos específicos del proveedor:
  • application/vnd.microsoft.card.adaptive: una tarjeta enriquecida que puede contener cualquier combinación de texto, voz, imágenes, botones y campos de entrada. Establezca la propiedad content en un objeto AdaptiveCard.
  • application/vnd.microsoft.card.animation: una tarjeta enriquecida que reproduce la animación. Establezca la propiedad content en un objeto AnimationCard.
  • application/vnd.microsoft.card.audio: una tarjeta enriquecida que reproduce archivos de audio. Establezca la propiedad content en un objeto AudioCard.
  • application/vnd.microsoft.card.hero: una tarjeta Hero. Establezca la propiedad content en un objeto HeroCard.
  • application/vnd.microsoft.card.receipt: una tarjeta de confirmación. Establezca la propiedad content en un objeto ReceiptCard.
  • application/vnd.microsoft.card.signin: una tarjeta de inicio de sesión de usuario. Establezca la propiedad content en un objeto SignInCard.
  • application/vnd.microsoft.card.thumbnail: una tarjeta en miniatura. Establezca la propiedad content en un objeto ThumbnailCard.
  • application/vnd.microsoft.card.video: una tarjeta enriquecida que reproduce vídeos. Establezca la propiedad content en un objeto VideoCard.
contentUrl Cadena Dirección URL del contenido de los datos adjuntos. Por ejemplo, si los datos adjuntos son una imagen, puede establecer contentUrl en la dirección URL que representa la ubicación de la imagen. Los protocolos compatibles son: HTTP, HTTPS, archivos y datos.
name Cadena Nombre de los datos adjuntos.
thumbnailUrl Cadena Dirección URL de una imagen en miniatura que el canal puede utilizar si admite el uso de una forma alternativa más pequeña de content o contentUrl. Por ejemplo, si establece contentType en application/word y contentUrl en la ubicación del documento de Word, puede incluir una imagen en miniatura que representa el documento. El canal puede mostrar la imagen en miniatura en lugar del documento. Cuando el usuario hace clic en la imagen, el canal abre el documento.

Volver a la tabla de esquema

Objeto AttachmentData

Describe los datos adjuntos.

Propiedad Tipo Descripción
name Cadena Nombre de los datos adjuntos.
originalBase64 Cadena Contenido de los datos adjuntos.
thumbnailBase64 Cadena Contenido de los datos adjuntos en miniatura.
type String Tipo de contenido de los datos adjuntos.

Volver a la tabla de esquema

Objeto AttachmentInfo

Metadatos de los datos adjuntos.

Propiedad Tipo Descripción
name Cadena Nombre de los datos adjuntos.
type String Tipo de contenido de los datos adjuntos.
vistas AttachmentView[] Matriz de objetos AttachmentView que representan las vistas disponibles para los datos adjuntos.

Volver a la tabla de esquema

Objeto AttachmentView

Define un objeto que representa una vista disponible para los datos adjuntos.

Propiedad Tipo Descripción
size Número Tamaño del archivo.
viewId Cadena Identificador de la vista.

Volver a la tabla de esquema

Objeto AudioCard

Define una tarjeta que puede reproducir un archivo de audio.

Propiedad Tipo Descripción
aspect Cadena Relación de aspecto de la miniatura que se especifica en la propiedad image. Los valores válidos son 16:9 y 4:3.
autoloop Booleano Marca que indica si se debe reproducir la lista de archivos de audio cuando finaliza la última. Establezca esta propiedad en true para reproducir los archivos de audio automáticamente; de lo contrario, establézcala en false. El valor predeterminado es true.
autostart Booleano Marca que indica si se debe reproducir automáticamente el archivo de audio cuando se muestra la tarjeta. Establezca esta propiedad en true para reproducir el audio automáticamente; de lo contrario, establézcala en false. El valor predeterminado es true.
buttons CardAction[] Matriz de objetos CardAction que permite al usuario realizar una o varias acciones. El canal determina el número de botones que se pueden especificar.
duration Cadena La longitud del contenido multimedia, en el formato de duración ISO 8601.
image ThumbnailUrl Un objeto ThumbnailUrl que especifica la imagen que se mostrará en la tarjeta.
media MediaUrl[] Matriz de objetos MediaUrl. Cuando este campo contiene más de una dirección URL, cada dirección URL es un formato alternativo del mismo contenido.
shareable Booleano Marca que indica si los archivos de audio compartirse con otros usuarios. Establezca esta propiedad en true si el audio puede compartirse; de lo contrario, en false. El valor predeterminado es true.
subtitle Cadena Subtítulo que se mostrará debajo del título de la tarjeta.
texto Cadena Descripción o mensaje para mostrar debajo del título o subtítulo de la tarjeta.
title Cadena Título de la tarjeta.
value Object Parámetro complementario de esta tarjeta.

Volver a la tabla de esquema

Objeto CardAction

Define una acción en la que se puede hacer clic con un botón.

Propiedad Tipo Descripción
channelData Cadena Datos específicos del canal asociados a esta acción.
displayText Cadena Texto que aparecerá en la fuente del chat si se hace clic en el botón.
image Cadena Dirección URL de la imagen que aparecerá en el botón junto a la etiqueta de texto.
texto Cadena Texto para la acción.
title Cadena Descripción del texto que aparece en el botón.
type String Tipo de acción que se va a realizar. Para obtener una lista de valores válidos, vea Incorporación de tarjetas enriquecidas a mensajes.
value Object Parámetro complementario de la acción. El comportamiento de esta propiedad variará según el objeto type de la acción. Para más información, vea Incorporación de datos adjuntos de tarjetas enriquecidas a mensajes.

Volver a la tabla de esquema

Objeto CardImage

Define una imagen para mostrarla en una tarjeta.

Propiedad Tipo Descripción
alt Cadena Descripción de la imagen. Debe incluir la descripción para admitir la accesibilidad.
tap CardAction Un objeto CardAction que especifica la acción que se realizará si el usuario pulsa o hace clic en la imagen.
url Cadena Dirección URL del origen de la imagen o del binario Base64 de la imagen (por ejemplo, data:image/png;base64,iVBORw0KGgo...).

Volver a la tabla de esquema

Objeto ChannelAccount

Define un bot o cuenta de usuario en el canal.

Propiedad Tipo Descripción
aadObjectId Cadena Id. de objeto de esta cuenta dentro de Microsoft Entra ID.
id Cadena Identificador único del usuario o bot en este canal.
name Cadena Nombre descriptivo del bot o el usuario.
role Cadena Rol de la entidad que se encuentra detrás de la cuenta. user (usuario) o bot.

Volver a la tabla de esquema

Objeto ConversationAccount

Define una conversación en un canal.

Propiedad Tipo Descripción
aadObjectId Cadena Id. de objeto de esta cuenta dentro de Microsoft Entra ID.
conversationType Cadena Indica el tipo de conversación en canales que distinguen entre tipos de conversación (por ejemplo, grupo o personal).
id Cadena Identificador de la conversación. El identificador es único para cada canal. Si el canal inicia la conversación, establece este identificador; de lo contrario, el bot establece esta propiedad en el identificador que obtiene con la respuesta cuando inicia la conversación (consulte Crear conversación).
isGroup Booleano Marca que indica si la conversación contiene más de dos participantes en el momento en que se generó la actividad. Se establece en true si se trata de una conversación de grupo; en caso contrario, en false. El valor predeterminado es false.
name Cadena Un nombre para mostrar que se puede usar para identificar la conversación.
role Cadena Rol de la entidad que se encuentra detrás de la cuenta. user (usuario) o bot.
tenantId Cadena Identificador del inquilino de esta conversación.

Volver a la tabla de esquema

Objeto ConversationMembers

Define los miembros de una conversación.

Propiedad Tipo Descripción
id Cadena El identificador de la conversación.
members ChannelAccount[] Lista de miembros de esta conversación.

Volver a la tabla de esquema

Objeto ConversationParameters

Define los parámetros para crear una conversación.

Propiedad Tipo Descripción
activity Actividad El mensaje inicial que se envía a la conversación cuando se crea.
bot ChannelAccount Información de la cuenta de canal necesaria para enrutar un mensaje al bot.
channelData Object Carga útil específica del canal para crear la conversación.
isGroup Booleano Indica si se trata de una conversación de grupo.
members ChannelAccount[] Información de la cuenta de canal necesaria para enrutar un mensaje a cada usuario.
tenantId Cadena El identificador del inquilino en el que se debe crear la conversación.
topicName Cadena Tema de la conversación. Esta propiedad solo se usa si un canal la admite.

Volver a la tabla de esquema

Objeto ConversationReference

Define un punto concreto de una conversación.

Propiedad Tipo Descripción
activityId Cadena Identificador que identifica de forma única la actividad a la que hace referencia este objeto.
bot ChannelAccount Un objeto ChannelAccount que identifica el bot en la conversación a la que este objeto hace referencia.
channelId Cadena Un identificador que identifica de forma única el canal en la conversación a la que este objeto hace referencia.
conversation ConversationAccount Un objeto ConversationAccount que define la conversación a la que este objeto hace referencia.
serviceUrl Cadena Dirección URL que especifica el punto de conexión de servicio del canal de la conversación a la que este objeto hace referencia.
usuario ChannelAccount Un objeto ChannelAccount que identifica al usuario en la conversación a la que este objeto hace referencia.

Volver a la tabla de esquema

Objeto ConversationResourceResponse

Define una respuesta para Crear conversación.

Propiedad Tipo Descripción
activityId Cadena Identificador de la actividad, si se envía.
id Cadena Identificador del recurso.
serviceUrl Cadena Punto de conexión de servicio en el que se pueden realizar las operaciones relacionadas con la conversación.

Volver a la tabla de esquema

Objeto ConversationsResult

Define el resultado de Obtener conversaciones.

Propiedad Tipo Descripción
conversaciones ConversationMembers[] Los miembros de cada una de las conversaciones.
continuationToken Cadena El token de continuación que se puede usar en las llamadas subsiguientes a Obtener conversaciones.

Volver a la tabla de esquema

Objeto Entity

Objeto de metadatos que pertenece a una actividad.

Propiedad Tipo Descripción
type String Tipo de esta entidad (RFC 3987 IRI).

Volver a la tabla de esquema

Objeto Error

Objeto que representa la información de error.

Propiedad Tipo Descripción
code Cadena Código de error.
innerHttpError InnerHttpError Objeto que representa el error HTTP interno.
message String Descripción del error.

Volver a la tabla de esquema

Objeto ErrorResponse

Define una respuesta de la API HTTP.

Propiedad Tipo Descripción
error Error Un objeto Error que contiene información sobre el error.

Volver a la tabla de esquema

Objeto Fact

Define un par clave-valor que contiene un hecho.

Propiedad Tipo Descripción
key Cadena Nombre del hecho. Por ejemplo, inserción en el repositorio. La clave se usa como una etiqueta al mostrar el valor del hecho.
value Cadena Valor del hecho. Por ejemplo, 10 de octubre de 2016.

Volver a la tabla de esquema

Objeto Geocoordinates

Define una ubicación geográfica mediante las coordenadas del sistema geodésico mundial (WSG84).

Propiedad Tipo Descripción
elevation Número Elevación de la ubicación.
latitude Número Latitud de la ubicación.
longitude Número Longitud de la ubicación.
name Cadena Nombre de la ubicación.
type String Tipo de este objeto . Siempre se establece en GeoCoordinates.

Volver a la tabla de esquema

Objeto HeroCard

Define una tarjeta con una imagen grande, título, texto y botones de acción.

Propiedad Tipo Descripción
buttons CardAction[] Matriz de objetos CardAction que permite al usuario realizar una o varias acciones. El canal determina el número de botones que se pueden especificar.
images CardImage[] Matriz de objetos CardImage que especifica la imagen que se mostrará en la tarjeta. Una tarjeta Hero contiene solo una imagen.
subtitle Cadena Subtítulo que se mostrará debajo del título de la tarjeta.
tap CardAction Un objeto CardAction que especifica la acción que se realizará si el usuario pulsa o hace clic en la tarjeta. Puede ser la misma acción que uno de los botones o una acción diferente.
texto Cadena Descripción o mensaje para mostrar debajo del título o subtítulo de la tarjeta.
title Cadena Título de la tarjeta.

Volver a la tabla de esquema

Objeto InnerHttpError

Objeto que representa un error HTTP interno.

Propiedad Tipo Descripción
statusCode Número Código de estado HTTP de la solicitud con error.
cuerpo Object Cuerpo de la solicitud con error.

Volver a la tabla de esquema

Objeto MediaEventValue

Parámetros complementarios para eventos multimedia.

Propiedad Tipo Descripción
cardValue Object Parámetro de devolución de llamada especificado en el campo Valor de la tarjeta multimedia que originó este evento.

Volver a la tabla de esquema

Objeto MediaUrl

Define la dirección URL al origen de un archivo multimedia.

Propiedad Tipo Descripción
profile Cadena Sugerencia que describe el contenido del elemento multimedia.
url Cadena Dirección URL del origen del archivo multimedia.

Volver a la tabla de esquema

Objeto Mention

Define un usuario o un bot que se mencionó en la conversación.

Propiedad Tipo Descripción
mentioned ChannelAccount Un objeto ChannelAccount que especifica el usuario o el bot que se ha mencionado. Algunos canales como Slack asignan nombres por conversación, por lo que es posible que el nombre mencionado del bot (en la propiedad recipient del mensaje) difiera del identificador especificado cuando se registró el bot. Sin embargo, los identificadores de cuenta podrían ser los mismos.
texto Cadena El usuario o bot como se mencionaron en la conversación. Por ejemplo, si el mensaje es "@ColorBot, elígeme un color nuevo", esta propiedad se establecería en @ColorBot. No todos los canales establecen esta propiedad.
type String Tipo de este objeto. Siempre se establece en Mention.

Volver a la tabla de esquema

Objeto MessageReaction

Define una reacción a un mensaje.

Propiedad Tipo Descripción
type String Tipo de reacción. like o plusOne.

Volver a la tabla de esquema

Objeto PagedMembersResult

Página de miembros que devuelve la operación Obtener los miembros de la conversación paginados.

Propiedad Tipo Descripción
continuationToken Cadena El token de continuación que se puede usar en las llamadas subsiguientes a la operación Obtener los miembros de la conversación paginados.
members ChannelAccount[] Una matriz de miembros de la conversación.

Volver a la tabla de esquema

Objeto Place

Define un lugar mencionado en la conversación.

Propiedad Tipo Descripción
address Object Dirección de un lugar. Esta propiedad puede ser una cadena o un objeto complejo del tipo PostalAddress.
geo GeoCoordinates Un objeto GeoCoordinates que especifica las coordenadas geográficas de un lugar.
hasMap Object Mapa del lugar. Esta propiedad puede ser de tipo string (URL) o un objeto complejo de tipo Map.
name Cadena Nombre del lugar.
type String Tipo de este objeto. Siempre se establece en Place.

Volver a la tabla de esquema

Objeto ReceiptCard

Define una tarjeta que contiene una recepción de una compra.

Propiedad Tipo Descripción
buttons CardAction[] Matriz de objetos CardAction que permite al usuario realizar una o varias acciones. El canal determina el número de botones que se pueden especificar.
facts Fact[] Matriz de objetos Fact que especifican información sobre la compra. Por ejemplo, la lista de hechos de la factura de la estancia en un hotel puede incluir la fecha de entrada y la fecha de salida. El canal determina el número de hechos que se pueden especificar.
items ReceiptItem[] Matriz de objetos ReceiptItem que especifican los elementos comprados.
tap CardAction Un objeto CardAction que especifica la acción que se realizará si el usuario pulsa o hace clic en la tarjeta. Puede ser la misma acción que uno de los botones o una acción diferente.
tax Cadena Una cadena con formato de moneda que especifica la cuantía de los impuestos aplicados a la compra.
title Cadena Título que se muestra en la parte superior de la factura.
total Cadena Una cadena con formato de moneda que especifica el precio total de la compra, incluidos todos los impuestos aplicables.
vat Cadena Una cadena con formato de moneda que especifica la cuantía del impuesto sobre el valor añadido (IVA) aplicado al precio de compra.

Volver a la tabla de esquema

Objeto ReceiptItem

Define un elemento de línea dentro de una confirmación.

Propiedad Tipo Descripción
image CardImage Un objeto CardImage que especifica la imagen en miniatura que se mostrará junto al elemento de línea.
price Cadena Una cadena con formato de moneda que especifica el precio total de todas las unidades compradas.
quantity Cadena Una cadena numérica que especifica el número de unidades compradas.
subtitle Cadena Subtítulo para mostrar debajo del título del elemento de línea.
tap CardAction Un objeto CardAction que especifica la acción que se realizará si el usuario pulsa o hace clic en el elemento de línea.
texto Cadena Descripción del elemento de línea.
title Cadena Título del elemento de línea.

Volver a la tabla de esquema

Objeto ResourceResponse

Define una respuesta que contiene un identificador de recurso.

Propiedad Tipo Descripción
id Cadena Identificador que distingue de manera única el recurso.

Volver a la tabla de esquema

Objeto SemanticAction

Define una referencia a una acción mediante programación.

Propiedad Tipo Descripción
entities Object Objeto en el que el valor de cada propiedad es un objeto Entity (entidad).
id Cadena Identificador de esta acción.
state Cadena Estado de esta acción. Los valores permitidos son: start (iniciar), continue (continuar), done (listo).

Volver a la tabla de esquema

Objeto SignInCard

Define una tarjeta que permite a un usuario iniciar sesión en un servicio.

Propiedad Tipo Descripción
buttons CardAction[] Matriz de objetos CardAction que permite al usuario iniciar sesión en un servicio. El canal determina el número de botones que se pueden especificar.
texto Cadena Descripción o mensaje para incluir en la tarjeta de inicio de sesión.

Volver a la tabla de esquema

Objeto SuggestedActions

Define las opciones que puede elegir un usuario.

Propiedad Tipo Descripción
actions CardAction[] Matriz de objetos CardAction que definen las acciones sugeridas.
to String[] Matriz de cadenas que contiene los identificadores de los destinatarios a los que se mostrarán las acciones sugeridas.

Volver a la tabla de esquema

Objeto TextHighlight

Hace referencia a una subcadena de contenido dentro de otro campo.

Propiedad Tipo Descripción
occurrence Número Aparición del campo de texto en el texto al que se hace referencia, en caso de que existan varios.
texto Cadena Define el fragmento de texto que se va a resaltar.

Volver a la tabla de esquema

Objeto ThumbnailCard

Define una tarjeta con una imagen en miniatura, título, texto y botones de acción.

Propiedad Tipo Descripción
buttons CardAction[] Matriz de objetos CardAction que permite al usuario realizar una o varias acciones. El canal determina el número de botones que se pueden especificar.
images CardImage[] Matriz de objetos CardImage que especifican las imágenes en miniatura que se mostrarán en la tarjeta. El canal determina el número de imágenes en miniatura que se pueden especificar.
subtitle Cadena Subtítulo que se mostrará debajo del título de la tarjeta.
tap CardAction Un objeto CardAction que especifica la acción que se realizará si el usuario pulsa o hace clic en la tarjeta. Puede ser la misma acción que uno de los botones o una acción diferente.
texto Cadena Descripción o mensaje para mostrar debajo del título o subtítulo de la tarjeta.
title Cadena Título de la tarjeta.

Volver a la tabla de esquema

Objeto ThumbnailUrl

Define la dirección URL al origen de una imagen.

Propiedad Tipo Descripción
alt Cadena Descripción de la imagen. Debe incluir la descripción para admitir la accesibilidad.
url Cadena Dirección URL del origen de la imagen o del binario Base64 de la imagen (por ejemplo, data:image/png;base64,iVBORw0KGgo...).

Volver a la tabla de esquema

Objeto Transcript

Una colección de actividades que se cargará mediante Enviar historial de la conversación.

Propiedad Tipo Descripción
actividades array Una matriz de objetos Activity. Deben tener un identificador único y una marca de tiempo.

Volver a la tabla de esquema

Objeto VideoCard

Define una tarjeta que puede reproducir vídeos.

Propiedad Tipo Descripción
aspect Cadena Relación de aspecto de un vídeo. 16:9 o 4:3.
autoloop Booleano Marca que indica si se debe reproducir la lista de vídeos cuando finaliza la última. Establezca esta propiedad en true para reproducir los vídeos automáticamente; de lo contrario, establézcala en false. El valor predeterminado es true.
autostart Booleano Marca que indica si se deben reproducir automáticamente los vídeos cuando se muestra la tarjeta. Establezca esta propiedad en true para reproducir los vídeos automáticamente; de lo contrario, establézcala en false. El valor predeterminado es true.
buttons CardAction[] Matriz de objetos CardAction que permite al usuario realizar una o varias acciones. El canal determina el número de botones que se pueden especificar.
duration Cadena La longitud del contenido multimedia, en el formato de duración ISO 8601.
image ThumbnailUrl Un objeto ThumbnailUrl que especifica la imagen que se mostrará en la tarjeta.
media MediaUrl[] Matriz de MediaUrl. Cuando este campo contiene más de una dirección URL, cada dirección URL es un formato alternativo del mismo contenido.
shareable Booleano Marca que indica si los vídeos pueden compartirse con otros usuarios. Establezca esta propiedad en true si los vídeos pueden compartirse; de lo contrario, en false. El valor predeterminado es true.
subtitle Cadena Subtítulo que se mostrará debajo del título de la tarjeta.
texto Cadena Descripción o mensaje para mostrar debajo del título o subtítulo de la tarjeta.
title Cadena Título de la tarjeta.
value Object Parámetro complementario de esta tarjeta.

Volver a la tabla de esquema