Referencia de API: Direct Line API 1.1API reference - Direct Line API 1.1

Importante

Este artículo contiene información de referencia para Direct Line API 1.1.This article contains reference information for Direct Line API 1.1. Si va a crear una nueva conexión entre la aplicación cliente y el bot, use Direct Line API 3.0 en su lugar.If you are creating a new connection between your client application and bot, use Direct Line API 3.0 instead.

Para permitir que su aplicación cliente se comunique con su bot, puede usar Direct Line API 1.1.You can enable your client application to communicate with your bot by using Direct Line API 1.1. Direct Line API 1.1 usa REST y JSON estándar del sector mediante HTTPS.Direct Line API 1.1 uses industry-standard REST and JSON over HTTPS.

URI baseBase URI

Para acceder a Direct Line API 1.1, use este URI base para todas las solicitudes de API:To access Direct Line API 1.1, use this base URI for all API requests:

https://directline.botframework.com

encabezadosHeaders

Además de los encabezados de solicitud HTTP estándar, una solicitud de Direct Line API debe incluir un encabezado Authorization que especifique un secreto o un token para autenticar al cliente que emite la solicitud.In addition to the standard HTTP request headers, a Direct Line API request must include an Authorization header that specifies a secret or token to authenticate the client that is issuing the request. Puede especificar el encabezado Authorization mediante el esquema "Bearer" o "BotConnector".You can specify the Authorization header using either the "Bearer" scheme or the "BotConnector" scheme.

Esquema Bearer:Bearer scheme:

Authorization: Bearer SECRET_OR_TOKEN

Esquema BotConnector:BotConnector scheme:

Authorization: BotConnector SECRET_OR_TOKEN

Para más información sobre cómo obtener un secreto o un token que el cliente pueda usar para autenticar sus solicitudes de Direct Line API, consulte Autenticación.For details about how to obtain a secret or token that your client can use to authenticate its Direct Line API requests, see Authentication.

Códigos de estado HTTPHTTP status codes

El código de estado HTTP que se devuelve con cada respuesta indica el resultado de la solicitud correspondiente.The HTTP status code that is returned with each response indicates the outcome of the corresponding request.

Código de estado HTTPHTTP status code SignificadoMeaning
200200 La solicitud finalizó correctamente.The request succeeded.
204204 La solicitud se realizó correctamente, pero no se devolvió ningún contenido.The request succeeded but no content was returned.
400400 La solicitud tenía formato incorrecto o era incorrecta por otro motivo.The request was malformed or otherwise incorrect.
401401 El cliente no está autorizado a realizar solicitudes.The client is not authorized to make the request. A menudo, este código de estado se produce porque falta el encabezado Authorization o tiene un formato incorrecto.Often this status code occurs because the Authorization header is missing or malformed.
403403 El cliente no tiene permitido llevar a cabo la operación solicitada.The client is not allowed to perform the requested operation. A menudo, este código de estado se produce porque el encabezado Authorization especifica un token o un secreto no válidos.Often this status code occurs because the Authorization header specifies an invalid token or secret.
404404 No se encontró el recurso solicitado.The requested resource was not found. Normalmente, este código de estado indica un URI de solicitud no válido.Typically this status code indicates an invalid request URI.
500500 Se ha producido un error interno del servidor en el servicio de Direct LineAn internal server error occurred within the Direct Line service
502502 Se produjo un error en el bot; el bot no está disponible o devolvió un error.A failure occurred within the bot; the bot is unavailable or returned an error. Se trata de un código de error común.This is a common error code.

Operaciones con tokensToken operations

Use estas operaciones para crear o actualizar un token que un cliente pueda utilizar para acceder a una conversación única.Use these operations to create or refresh a token that a client can use to access a single conversation.

OperaciónOperation DescripciónDescription
Generar tokenGenerate Token Genera un token para una conversación nueva.Generate a token for a new conversation.
Actualizar tokenRefresh Token Actualiza un token.Refresh a token.

Generar tokenGenerate Token

Genera un token válido para una conversación.Generates a token that is valid for one conversation.

POST /api/tokens/conversation
ContenidoContent DescripciónDescription
Cuerpo de la solicitudRequest body N/Dn/a
DevuelveReturns Una cadena que representa el tokenA string that represents the token

Actualizar tokenRefresh Token

Actualiza el token.Refreshes the token.

GET /api/tokens/{conversationId}/renew
ContenidoContent DescripciónDescription
Cuerpo de la solicitudRequest body N/Dn/a
DevuelveReturns Una cadena que representa el nuevo tokenA string that represents the new token

Operaciones con conversacionesConversation operations

Use estas operaciones para abrir una conversación con el bot e intercambiar mensajes entre el cliente y el bot.Use these operations to open a conversation with your bot and exchange messages between client and bot.

OperaciónOperation DescripciónDescription
Iniciar conversaciónStart Conversation Abre una nueva conversación con el bot.Opens a new conversation with the bot.
Get MessagesGet Messages Recibe mensajes del bot.Retrieves messages from the bot.
Enviar un mensajeSend a Message Envía un mensaje al bot.Sends a message to the bot.
Cargar y enviar archivosUpload and Send File(s) Carga y envía archivos como adjuntos.Uploads and sends file(s) as attachment(s).

Iniciar conversaciónStart Conversation

Abre una nueva conversación con el bot.Opens a new conversation with the bot.

POST /api/conversations
ContenidoContent DescripciónDescription
Cuerpo de la solicitudRequest body N/Dn/a
DevuelveReturns Un objeto ConversationA Conversation object

Obtener mensajesGet Messages

Recupera los mensajes del bot para la conversación especificada.Retrieves messages from the bot for the specified conversation. Establezca el parámetro watermark en el URI de la solicitud para indicar el mensaje más reciente visto por el cliente.Set the watermark parameter in the request URI to indicate the most recent message seen by the client.

GET /api/conversations/{conversationId}/messages?watermark={watermark_value}
ContenidoContent DescripciónDescription
Cuerpo de la solicitudRequest body N/Dn/a
DevuelveReturns Un objeto MessageSet.A MessageSet object. La respuesta contiene watermark como propiedad del objeto MessageSet.The response contains watermark as a property of the MessageSet object. Los clientes deben desplazarse por los mensajes disponibles haciendo avanzar el valor watermark hasta que no se devuelvan mensajes.Clients should page through the available messages by advancing the watermark value until no messages are returned.

Enviar un mensajeSend a Message

Envía un mensaje al bot.Sends a message to the bot.

POST /api/conversations/{conversationId}/messages
ContenidoContent DescripciónDescription
Cuerpo de la solicitudRequest body Un objeto MessageA Message object
DevuelveReturns No se devuelven datos en el cuerpo de la respuesta.No data is returned in body of the response. El servicio responde con un código de estado HTTP 204, si el mensaje se envió correctamente.The service responds with an HTTP 204 status code if the message was sent successfully. El cliente puede obtener su mensaje enviado (junto con los mensajes que el bot ha enviado al cliente) mediante la operación Obtener mensajes.The client may obtain its sent message (along with any messages that the bot has sent to the client) by using the Get Messages operation.

Cargar y enviar archivosUpload and Send File(s)

Carga y envía archivos como adjuntos.Uploads and sends file(s) as attachment(s). Establezca el parámetro userId en el URI de la solicitud para especificar el identificador del usuario que envía los datos adjuntos.Set the userId parameter in the request URI to specify the ID of the user that is sending the attachments.

POST /api/conversations/{conversationId}/upload?userId={userId}
ContenidoContent DescripciónDescription
Cuerpo de la solicitudRequest body Para un único dato adjunto, rellene el cuerpo de la solicitud con el contenido del archivo.For a single attachment, populate the request body with the file contents. Para varios datos adjuntos, cree un cuerpo de solicitud de varias partes que contenga una parte para cada dato adjunto y, además (de manera opcional), una parte para el objeto Message que debe actuar como contenedor para los datos adjuntos especificados.For multiple attachments, create a multipart request body that contains one part for each attachment, and also (optionally) one part for the Message object that should serve as the container for the specified attachment(s). Para más información, consulte Envío de una actividad al bot.For more information, see Send a message to the bot.
DevuelveReturns No se devuelven datos en el cuerpo de la respuesta.No data is returned in body of the response. El servicio responde con un código de estado HTTP 204, si el mensaje se envió correctamente.The service responds with an HTTP 204 status code if the message was sent successfully. El cliente puede obtener su mensaje enviado (junto con los mensajes que el bot ha enviado al cliente) mediante la operación Obtener mensajes.The client may obtain its sent message (along with any messages that the bot has sent to the client) by using the Get Messages operation.

Nota

Los archivos cargados se eliminan después de 24 horas.Uploaded files are deleted after 24 hours.

SchemaSchema

El esquema de Direct Line 1.1 es una copia simplificada del esquema de Bot Framework v1 que incluye los siguientes objetos.Direct Line 1.1 schema is a simplified copy of the Bot Framework v1 schema that includes the following objects.

Objeto de mensajeMessage object

Define un mensaje que un cliente envía a un bot o recibe de un bot.Defines a message that a client sends to a bot or receives from a bot.

PropiedadProperty TipoType DescripciónDescription
idid stringstring Identificador que identifica de forma única el mensaje (asignado por Direct Line).ID that uniquely identifies the message (assigned by Direct Line).
conversationIdconversationId stringstring Identificador que identifica la conversación.ID that identifies the conversation.
createdcreated stringstring Fecha y hora en que se creó el mensaje, expresado en el formato ISO-8601.Date and time that the message was created, expressed in ISO-8601 format.
fromfrom stringstring Identificador que identifica el usuario que es el remitente del mensaje.ID that identifies the user that is the sender of the message. Al crear un mensaje, los clientes deben establecer esta propiedad en un identificador de usuario estable.When creating a message, clients should set this property to a stable user ID. Aunque Direct Line asignará un identificador de usuario si no se proporciona ninguno, esto da lugar normalmente a un comportamiento inesperado.Although Direct Line will assign a user ID if none is supplied, this typically results in unexpected behavior.
texttext stringstring Texto del mensaje que se envía del usuario al bot o del bot al usuario.Text of the message that is sent from user to bot or bot to user.
channelDatachannelData objectobject Objeto que incluye contenido específico de canal.An object that contains channel-specific content. Algunos canales proporcionan características que requieren información adicional que no se puede representar mediante el esquema de datos adjuntos.Some channels provide features that require additional information that cannot be represented using the attachment schema. Para esos casos, establezca esta propiedad en el contenido específico de canal tal como se define en la documentación del canal.For those cases, set this property to the channel-specific content as defined in the channel's documentation. Estos datos se envían sin modificar entre el cliente y el bot.This data is sent unmodified between client and bot. Esta propiedad se debe establecer en un objeto complejo o dejarse vacía.This property must either be set to a complex object or left empty. No la establezca en una cadena, número u otro tipo simple.Do not set it to a string, number, or other simple type.
imagesimages string[]string[] Matriz de cadenas que contiene las direcciones URL para las imágenes que contiene el mensaje.Array of strings that contains the URL(s) for the image(s) that the message contains. En algunos casos, las cadenas de esta matriz pueden ser direcciones URL relativas.In some cases, strings in this array may be relative URLs. Si cualquier cadena de esta matriz no comienza con "http" o "https", anteponga https://directline.botframework.com a la cadena para formar la dirección URL completa.If any string in this array does not begin with either "http" or "https", prepend https://directline.botframework.com to the string to form the complete URL.
attachmentsattachments Attachment[]Attachment[] Matriz de objetos Attachment que representan los datos adjuntos que no son imágenes que contiene el mensaje.Array of Attachment objects that represent the non-image attachments that the message contains. Cada objeto de la matriz contiene una propiedad url y una propiedad contentType.Each object in the array contains a url property and a contentType property. En los mensajes que recibe un cliente de un bot, la propiedad url puede especificar a veces una dirección URL relativa.In messages that a client receives from a bot, the url property may sometimes specify a relative URL. Para cualquier valor de propiedad url que no comience por "http" o "https", anteponga https://directline.botframework.com a la cadena para formar la dirección URL completa.For any url property value that does not begin with either "http" or "https", prepend https://directline.botframework.com to the string to form the complete URL.

En el ejemplo siguiente se muestra un objeto Message que contiene todas las propiedades posibles.The following example shows a Message object that contains all possible properties. En la mayoría de los casos al crear un mensaje, el cliente solo tiene que proporcionar la propiedad from y al menos una propiedad de contenido (por ejemplo, text, images, attachments o channelData).In most cases when creating a message, the client only needs to supply the from property and at least one content property (e.g., text, images, attachments, or channelData).

{
    "id": "CuvLPID4kDb|000000000000000004",
    "conversationId": "CuvLPID4kDb",
    "created": "2016-10-28T21:19:51.0357965Z",
    "from": "examplebot",
    "text": "Hello!",
    "channelData": {
        "examplefield": "abc123"
    },
    "images": [
        "/attachments/CuvLPID4kDb/0.jpg?..."
    ],
    "attachments": [
        {
            "url": "https://example.com/example.docx",
            "contentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
        }, 
        {
            "url": "https://example.com/example.doc",
            "contentType": "application/msword"
        }
    ]
}

Objeto MessageSetMessageSet object

Define un conjunto de mensajes.Defines a set of messages.

PropiedadProperty TipoType DescripciónDescription
messagesmessages Message[]Message[] Matriz de objetos Message.Array of Message objects.
watermarkwatermark stringstring Marca de agua máxima de mensajes dentro del conjunto.Maximum watermark of messages within the set. Un cliente puede usar el valor watermark para indicar el mensaje más reciente que ha visto al recuperar mensajes del bot.A client may use the watermark value to indicate the most recent message it has seen when retrieving messages from the bot.

Objeto AttachmentAttachment object

Define un dato adjunto que no es una imagen.Defines a non-image attachment.

PropiedadProperty TipoType DescripciónDescription
contentTypecontentType stringstring Tipo de elemento multimedia del contenido de los datos adjuntos.The media type of the content in the attachment.
urlurl stringstring Dirección URL del contenido de los datos adjuntos.URL for the content of the attachment.

Objeto ConversationConversation object

Define una conversación de Direct Line.Defines a Direct Line conversation.

PropiedadProperty TipoType DescripciónDescription
conversationIdconversationId stringstring Identificador que identifica de forma única la conversación para la cual el token especificado es válido.ID that uniquely identifies the conversation for which the specified token is valid.
tokentoken stringstring Token válido para la conversación especificada.Token that is valid for the specified conversation.
expires_inexpires_in numbernumber Número de segundos hasta que expira el token.Number of seconds until the token expires.

Objeto de errorError object

Define un error.Defines an error.

PropiedadProperty TipoType DescripciónDescription
codecode stringstring Código de error.Error code. Uno de estos valores: MissingProperty, MalformedData, NotFound, ServiceError, Internal, InvalidRange, NotSupported, NotAllowed, BadCertificate.One of these values: MissingProperty, MalformedData, NotFound, ServiceError, Internal, InvalidRange, NotSupported, NotAllowed, BadCertificate.
messagemessage stringstring Descripción del error.A description of the error.
statusCodestatusCode numbernumber Código de estado.Status code.

Objeto ErrorMessageErrorMessage object

Una carga estandarizada de errores de mensajes.A standardized message error payload.

PropiedadProperty TipoType DescripciónDescription
errorerror ErrorError Un objeto Error que contiene información sobre el error.An Error object that contains information about the error.