Referencia de API: DIRECT LINE API 3.0

Puede permitir que la aplicación cliente se comunique con el bot mediante Direct Line API 3.0. Direct Line API 3.0 usa REST estándar del sector y JSON a través de HTTPS.

Base URI

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	Base URI
  Europe	https://europe.directline.botframework.com
  India	https://india.directline.botframework.com

Headers

Además de los encabezados de solicitud HTTP estándar, una solicitud de API de Direct Line debe incluir un Authorization encabezado que especifique un secreto o token para autenticar al cliente que emite la solicitud. Especifique el Authorization encabezado con este formato:

Authorization: Bearer SECRET_OR_TOKEN

Para más información sobre cómo obtener un secreto o token que el cliente puede usar para autenticar sus solicitudes de API de Direct Line, 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.

Errors

Cualquier respuesta que especifique un código de estado HTTP en el intervalo 4xx o el intervalo 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 intervalo 4xx, inspeccione el objeto ErrorResponse para identificar la causa del error y resolver el problema antes de volver a enviar la solicitud.

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

Solicitud

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 de token

Use estas operaciones para crear o actualizar un token que un cliente pueda usar para acceder a una sola conversación.

Generar token

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

POST /v3/directline/tokens/generate

Actualizar token

Actualiza el token.

POST /v3/directline/tokens/refresh

Operaciones de conversación

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

Iniciar conversación

Abre una nueva conversación con el bot.

POST /v3/directline/conversations

Obtener información de conversación

Obtiene información sobre una conversación existente y también genera una nueva dirección URL de secuencia de WebSocket que un cliente puede usar para volver a conectarse a una conversación. Opcionalmente, puede proporcionar el watermark parámetro en el URI de solicitud para indicar el mensaje más reciente visto por el cliente.

GET /v3/directline/conversations/{conversationId}?watermark={watermark_value}

Obtener actividades

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

GET /v3/directline/conversations/{conversationId}/activities?watermark={watermark_value}

Enviar una actividad

Envía una actividad al bot.

POST /v3/directline/conversations/{conversationId}/activities

Cargar y enviar archivos

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

POST /v3/directline/conversations/{conversationId}/upload?userId={userId}

Schema

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

ActivitySet (objeto)

Define un conjunto de actividades.

Objeto Conversation

Define una conversación Direct Line.

TokenParameters (objeto)

Parámetros para crear un token.

Activities

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

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

Los clientes pueden recibir varias actividades del bot como parte de un ActivitySet.

Cuando un cliente envía un Activity objeto a un bot a través de Direct Line:

• La type propiedad especifica la actividad de tipo que envía (normalmente el mensaje).
• La from propiedad debe rellenarse con un identificador de usuario, elegido por el cliente.
• Los datos adjuntos pueden contener direcciones URL a los recursos o direcciones URL existentes cargados a través del punto de conexión de datos adjuntos de Direct Line.
• La channelData propiedad se conserva sin modificaciones.
• El tamaño total de la actividad, cuando se serializa en JSON y se cifra, no debe superar los 256 000 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.

Los clientes pueden enviar una sola actividad por solicitud.

Recursos adicionales

• Especificación del protocolo de actividad