Referencia de API: Direct Line API 3.0

  • Artículo

Para permitir que su aplicación cliente se comunique con su bot, puede usar Direct Line API 3.0. Direct Line API 3.0 usa REST y JSON estándares a través de HTTPS.

URI base

Para acceder a Direct Line API 3.0, use uno de estos URI base para todas las solicitudes de API:

Sugerencia

Es posible que se produzca un error en una solicitud si usa el URI base global para un bot regional, ya que algunas solicitudes podrían ir más allá de los límites geográficos.

Encabezados

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. Especifique el encabezado Authorization con este formato:

Authorization: Bearer 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.

Códigos de estado HTTP

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

Código de estado HTTP Significado
200 La solicitud finalizó correctamente.
201 La solicitud finalizó correctamente.
202 La solicitud se ha aceptado para 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 cliente no está autorizado para realizar la solicitud. A menudo, este código de estado se produce porque falta el encabezado Authorization o tiene un formato incorrecto.
403 El cliente no puede realizar la operación solicitada. La operación puede producir un error por los siguientes motivos.
  • Un token no válido: cuando la solicitud usa un token que era válido anteriormente pero ha expirado, la code propiedad del error que se devuelve dentro del objeto ErrorResponse se establece TokenExpireden .
  • Infracción de límite de datos: si el bot es un bot regional, pero el URI base no es regional, algunas solicitudes pueden ir más allá de los límites geográficos.
  • Un recurso de destino no válido: el bot o sitio de destino no es válido o se eliminó.
404 No se encontró el recurso solicitado. Normalmente, este código de estado indica un URI de solicitud no válido.
500 Se ha producido un error interno del servidor en el servicio de Direct Line.
502 El bot no está disponible o devolvió un error. Se trata de un código de error común.

Nota:

El código de estado HTTP 101 se usa en la ruta de acceso de conexión de WebSocket, aunque es probable que el cliente de WebSocket controle esto.

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.

Nota:

Los códigos de estado HTTP y los valores especificados en la propiedad code dentro del objeto ErrorResponse son estables. Los valores especificados en la propiedad message dentro del objeto ErrorResponse pueden cambiar con el tiempo.

Los fragmentos de código siguientes muestran un ejemplo de solicitud y la respuesta de error resultante.

Solicitar

POST https://directline.botframework.com/v3/directline/conversations/abc123/activities
[detail omitted]

Respuesta

HTTP/1.1 502 Bad Gateway
[other headers]

{
    "error": {
        "code": "BotRejectedActivity",
        "message": "Failed to send activity: bot returned an error"
    }
}

Operaciones con tokens

Use estas operaciones para crear o actualizar un token que un cliente pueda utilizar para acceder a una conversación única.

Operación Descripción
Generar token Genera un token para una conversación nueva.
Actualizar token Actualiza un token.

Generar token

Genera un token válido para una conversación.

POST /v3/directline/tokens/generate
Contenido Descripción
Cuerpo de la solicitud Un objeto TokenParameters
Devuelve Un objeto Conversation

Token de actualización

Actualiza el token.

POST /v3/directline/tokens/refresh
Contenido Descripción
Cuerpo de la solicitud N/D
Devuelve Un objeto Conversation

Operaciones con conversaciones

Use estas operaciones para abrir una conversación con sus bot e intercambie actividades entre el cliente y el bot.

Operación Descripción
Iniciar conversación Abre una nueva conversación con el bot.
Obtener información de la conversación Le permite obtener información sobre una conversación existente. Esta operación genera una nueva dirección URL de flujo de WebSocket que un cliente puede utilizar para reconectarse a una conversación.
Obtener actividades Recupera actividades del bot.
Enviar una actividad Envía una actividad al bot.
Cargar y enviar archivos Carga y envía archivos como adjuntos.

Iniciar conversación

Abre una nueva conversación con el bot.

POST /v3/directline/conversations
Contenido Descripción
Cuerpo de la solicitud Un objeto TokenParameters
Devuelve Un objeto Conversation

Obtener información de la conversación

Obtiene información sobre una conversación existente y también genera una nueva dirección URL de flujo de WebSocket que un cliente puede utilizar para reconectarse a una conversación. Como alternativa, se puede proporcionar el parámetro watermark en el URI de la solicitud para indicar el mensaje más reciente visto por el cliente.

GET /v3/directline/conversations/{conversationId}?watermark={watermark_value}
Contenido Descripción
Cuerpo de la solicitud N/D
Devuelve Un objeto Conversation

Obtener actividades

Recupera las actividades del bot para la conversación especificada. Como alternativa, se puede proporcionar el parámetro watermark en el URI de la solicitud para indicar el mensaje más reciente visto por el cliente.

GET /v3/directline/conversations/{conversationId}/activities?watermark={watermark_value}
Contenido Descripción
Cuerpo de la solicitud N/D
Devuelve Un objeto ActivitySet. La respuesta contiene watermark como propiedad del objeto ActivitySet. Los clientes deben desplazarse por las actividades disponibles haciendo avanzar el valor watermark hasta que no se devuelvan actividades.

Enviar una actividad

Envía una actividad al bot.

POST /v3/directline/conversations/{conversationId}/activities
Contenido Descripción
Cuerpo de la solicitud Un objeto Activity
Devuelve Un objeto ResourceResponse que contiene una propiedad id que especifica el id. de la actividad que se envió al bot.

Cargar y enviar archivos

Carga y envía archivos como adjuntos. Establecer el parámetro userId en el URI de la solicitud para especificar el id. del usuario que envía los adjuntos.

POST /v3/directline/conversations/{conversationId}/upload?userId={userId}
Contenido Descripción
Cuerpo de la solicitud Para un único dato adjunto, rellene el cuerpo de la solicitud con el contenido del archivo. Para varios archivos adjuntos, cree un cuerpo de solicitud de varias partes que contenga una parte para cada archivo adjunto y, además (de manera opcional), una parte para el objeto Activity que debe actuar como contenedor para los archivos adjuntos especificados. Para obtener más información, consulte Envío de una actividad al bot.
Devuelve Un objeto ResourceResponse que contiene una propiedad id que especifica el id. de la actividad que se envió al bot.

Nota:

Los archivos cargados se eliminan después de 24 horas.

Esquema

El esquema de Direct Line 3.0 incluye todos los objetos definidos por el esquema de Bot Framework, así como algunos objetos que son específicos de Direct Line.

Objeto ActivitySet

Define un conjunto de actividades.

Propiedad Tipo Descripción
actividades Actividad[] Matriz de objetos Activity.
watermark string Marca de agua máxima de actividades dentro del conjunto. Un cliente puede utilizar el valor watermark para indicar el mensaje más reciente que ha visto al recuperar actividades del bot o al generar una nueva dirección URL del flujo de WebSocket.

Objeto Conversation

Define una conversación de Direct Line.

Propiedad Tipo Descripción
conversationId string Identificador que identifica de forma única la conversación para la cual el token especificado es válido.
eTag string Una ETag (etiqueta de entidad) de HTTP.
expires_in number Número de segundos hasta que expira el token.
referenceGrammarId string Identificador de la gramática de referencia de este bot.
streamUrl string Dirección URL del flujo de mensajes de la conversación.
token string Token válido para la conversación especificada.

Objeto TokenParameters

Parámetros para crear un token.

Propiedad Tipo Descripción
eTag string Una ETag (etiqueta de entidad) de HTTP.
trustedOrigins string[] Orígenes de confianza para insertar dentro del token.
usuario ChannelAccount Cuenta de usuario para insertar dentro del token.

Actividades

Para cada Activity que un cliente recibe de un bot a través de Direct Line:

  • Se conservan las tarjetas de archivos adjuntos.
  • Las direcciones URL para los archivos adjuntos cargados se ocultan con un vínculo privado.
  • La propiedad channelData se conserva sin modificaciones.

Es posible que los clientes reciban varias actividades del bot como parte de un objeto ActivitySet.

Cuando un cliente envía un objeto Activity a un bot mediante Direct Line:

  • La type propiedad especifica la actividad de tipo que envía (normalmente el mensaje).
  • La propiedad from se debe rellenar con un id. de usuario elegido por el cliente.
  • Los archivos adjuntos pueden contener direcciones URL a los recursos existentes o direcciones URL cargadas a través del punto de conexión de los archivos adjuntos de Direct Line.
  • La propiedad channelData se conserva sin modificaciones.
  • El tamaño total de la actividad, cuando se serializa en JSON y se cifra, no debe superar los 256 K caracteres. Se recomienda mantener las actividades en menos de 150 000. Si se necesitan más datos, considere la posibilidad de dividir la actividad o usar datos adjuntos.

Es posible que los clientes envíen una única actividad por solicitud.

Recursos adicionales