Referencia de API: Direct Line API 3.0
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:
En el caso de los bots globales, use
https://directline.botframework.com
En el caso de un bot regional, escriba el siguiente URI según la región seleccionada:
Region URI base Europa https://europe.directline.botframework.com
India https://india.directline.botframework.com
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.
|
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.