Referencia de API para el servicio Bot Framework Connector

Artículo
12/20/2023

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.

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.

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.

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

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.

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.

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...`).

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.

Propiedad	Tipo	Descripción
id	Cadena	El identificador de la conversación.
members	ChannelAccount[]	Lista de miembros de esta 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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

Compartir vía

Referencia de API para el servicio Bot Framework Connector

URI base

Encabezados

Encabezados de solicitud

Encabezados de respuesta

Códigos de estado HTTP

Errores

Operaciones con conversaciones

Creación de conversación

Actividad de eliminación

Eliminar miembro de la conversación

Obtener miembros de la actividad

Obtener conversaciones

Obtener miembro de la conversación

Obtener miembros de la conversación

Obtener los miembros de la conversación paginados

Responder a actividad

Envío de historial de la conversación

Enviar a conversación

Actualizar actividad

Cargar datos adjuntos al canal

Operaciones con datos adjuntos

Obtención de información de datos adjuntos

Obtener datos adjuntos

Operaciones de estado (en desuso)

Esquema

Objeto Activity

Objeto AnimationCard

Objeto Attachment

Objeto AttachmentData

Objeto AttachmentInfo

Objeto AttachmentView

Objeto AudioCard

Objeto CardAction

Objeto CardImage

Objeto ChannelAccount

Objeto ConversationAccount

Objeto ConversationMembers

Objeto ConversationParameters

Objeto ConversationReference

Objeto ConversationResourceResponse

Objeto ConversationsResult

Objeto Entity

Objeto Error

Objeto ErrorResponse

Objeto Fact

Objeto Geocoordinates

Objeto HeroCard

Objeto InnerHttpError

Objeto MediaEventValue

Objeto MediaUrl

Objeto Mention

Objeto MessageReaction

Objeto PagedMembersResult

Objeto Place

Objeto ReceiptCard

Objeto ReceiptItem

Objeto ResourceResponse

Objeto SemanticAction

Objeto SignInCard

Objeto SuggestedActions

Objeto TextHighlight

Objeto ThumbnailCard

Objeto ThumbnailUrl

Objeto Transcript

Objeto VideoCard

Recursos adicionales

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).

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.

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.

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.