Recibir actividades del bot en Direct line API 3,0Receive activities from the bot in Direct Line API 3.0

Con el protocolo Direct Line 3.0, los clientes pueden recibir actividades mediante una secuencia de WebSocket o recuperar actividades mediante la emisión de solicitudes HTTP GET.Using the Direct Line 3.0 protocol, clients can receive activities via WebSocket stream or retrieve activities by issuing HTTP GET requests.

WebSocket frente a HTTP GETWebSocket vs HTTP GET

Un protocolo WebSocket de streaming inserta mensajes en los clientes, siempre y cuando la interfaz GET permita que los clientes soliciten mensajes explícitamente.A streaming WebSocket efficiently pushes messages to clients, whereas the GET interface enables clients to explicitly request messages. Aunque con frecuencia se prefiere el mecanismo WebSocket dada su eficacia, el mecanismo GET puede ser útil para los clientes que no pueden usar WebSockets.Although the WebSocket mechanism is often preferred due to its efficiency, the GET mechanism can be useful for clients that are unable to use WebSockets.

El servicio permite solo 1 conexión de WebSocket por conversación.The service allows only 1 WebSocket connection per conversation. Direct Line puede cerrar conexiones WebSocket adicionales con un valor de motivo de collision.Direct Line may close additional WebSocket connections with a reason value of collision.

No todos los tipos de actividad están disponibles mediante WebSocket y HTTP GET.Not all activity types are available both via WebSocket and via HTTP GET. En la tabla siguiente se describe la disponibilidad de los distintos tipos de actividad para los clientes que usan el protocolo Direct Line.The following table describes the availability of the various activity types for clients that use the Direct Line protocol.

Tipo de actividadActivity type DisponibilidadAvailability
messagemessage HTTP GET y WebSocketHTTP GET and WebSocket
typingtyping Solo WebSocketWebSocket only
conversationUpdateconversationUpdate No enviados o recibidos mediante el clienteNot sent/received via client
contactRelationUpdatecontactRelationUpdate No se admite en Direct LineNot supported in Direct Line
endOfConversationendOfConversation HTTP GET y WebSocketHTTP GET and WebSocket
todos los demás tipos de actividadall other activity types HTTP GET y WebSocketHTTP GET and WebSocket

Recepción de actividades mediante una secuencia de WebSocketReceive activities via WebSocket stream

Cuando un cliente envía una solicitud Iniciar conversación para abrir una conversación con un bot, la respuesta del servicio incluye una propiedad streamUrl que el cliente puede usar posteriormente para conectarse por medio de WebSocket.When a client sends a Start Conversation request to open a conversation with a bot, the service's response includes a streamUrl property that the client can subsequently use to connect via WebSocket. La dirección URL de la secuencia se autoriza previamente y, por tanto, la solicitud del cliente para conectarse mediante WebSocket NO requiere un encabezado Authorization.The stream URL is preauthorized and therefore the client's request to connect via WebSocket does NOT require an Authorization header.

En el ejemplo siguiente se muestra una solicitud que usa streamUrl para conectarse por medio de WebSocket.The following example shows a request that uses a streamUrl to connect via WebSocket.

-- connect to wss://directline.botframework.com --
GET /v3/directline/conversations/abc123/stream?t=RCurR_XV9ZA.cwA..."
Upgrade: websocket
Connection: upgrade
[other headers]

El servicio responde con el código de estado HTTP 101 ("Cambiando protocolos").The service responds with status code HTTP 101 ("Switching Protocols").

HTTP/1.1 101 Switching Protocols
[other headers]

Recepción de mensajesReceive messages

Después de conectarse mediante WebSocket, un cliente puede recibir estos tipos de mensajes del servicio Direct Line:After it connects via WebSocket, a client may receive these types of messages from the Direct Line service:

  • Un mensaje que contiene un elemento ActivitySet que incluye una o varias actividades y una marca de agua (se describe a continuación).A message that contains an ActivitySet that includes one or more activities and a watermark (described below).
  • Un mensaje vacío, que usa el servicio Direct Line para garantizar que la conexión sigue siendo válida.An empty message, which the Direct Line service uses to ensure the connection is still valid.
  • Tipos adicionales, que se definirán más adelante.Additional types, to be defined later. Estos tipos se identifican mediante las propiedades de la raíz JSON.These types are identified by the properties in the JSON root.

Un elemento ActivitySet contiene los mensajes que envían el bot y todos los usuarios de la conversación.An ActivitySet contains messages sent by the bot and by all users in the conversation. En el ejemplo siguiente se muestra un elemento ActivitySet que contiene un único mensaje.The following example shows an ActivitySet that contains a single message.

{
    "activities": [
        {
            "type": "message",
            "channelId": "directline",
            "conversation": {
                "id": "abc123"
            },
            "id": "abc123|0000",
            "from": {
                "id": "user1"
            },
            "text": "hello"
        }
    ],
    "watermark": "0000a-42"
}

Procesamiento de mensajesProcess messages

Un cliente debe realizar un seguimiento del valor watermark que recibe en cada ActivitySet, de modo que pueda usar la marca de agua para garantizar que no se pierde ningún mensaje en caso de que se pierda la conexión y sea necesario volver a conectarse a la conversación.A client should keep track of the watermark value that it receives in each ActivitySet, so that it may use the watermark to guarantee that no messages are lost if it loses its connection and needs to reconnect to the conversation. Si el cliente recibe un elemento ActivitySet donde la propiedad watermark falta o es null, debe omitir ese valor y no sobrescribir la marca de agua anterior que recibió.If the client receives an ActivitySet wherein the watermark property is null or missing, it should ignore that value and not overwrite the prior watermark that it received.

Un cliente debe omitir los mensajes vacíos que recibe del servicio Direct Line.A client should ignore empty messages that it receives from the Direct Line service.

Un cliente puede enviar mensajes vacíos al servicio Direct Line para comprobar la conectividad.A client may send empty messages to the Direct Line service to verify connectivity. El servicio Direct Line pasará por alto los mensajes vacíos que recibe del cliente.The Direct Line service will ignore empty messages that it receives from the client.

El servicio Direct Line puede forzar el cierre de la conexión de WebSocket en determinadas condiciones.The Direct Line service may forcibly close the WebSocket connection under certain conditions. Si el cliente no ha recibido una actividad endOfConversation, es posible que genere una nueva dirección URL de secuencia de WebSocket que puede usar para volver a conectarse a la conversación.If the client has not received an endOfConversation activity, it may generate a new WebSocket stream URL that it can use to reconnect to the conversation.

La secuencia de WebSocket contiene actualizaciones directas y mensajes muy recientes (desde que se emitió la llamada para conectarse mediante WebSocket) pero no incluye los mensajes enviados antes de la solicitud POST más reciente a /v3/directline/conversations/{id}.The WebSocket stream contains live updates and very recent messages (since the call to connect via WebSocket was issued) but it does not include messages that were sent prior to the most recent POST to /v3/directline/conversations/{id}. Para recuperar los mensajes enviados anteriormente en la conversación, use HTTP GET tal como se describe a continuación.To retrieve messages that were sent earlier in the conversation, use HTTP GET as described below.

Recuperación de actividades con HTTP GETRetrieve activities with HTTP GET

Los clientes que no pueden usar WebSockets pueden recuperar las actividades mediante HTTP GET.Clients that are unable to use WebSockets can retrieve activities by using HTTP GET.

Para recuperar mensajes de una conversación específica, emita una solicitud GET al punto de conexión /v3/directline/conversations/{conversationId}/activities y, si lo desea, especifique el parámetro watermark para indicar el mensaje más reciente visto por el cliente.To retrieve messages for a specific conversation, issue a GET request to the /v3/directline/conversations/{conversationId}/activities endpoint, optionally specifying the watermark parameter to indicate the most recent message seen by the client.

Los fragmentos de código siguientes proporcionan un ejemplo de la solicitud y respuesta de Obtener actividades de conversación.The following snippets provide an example of the Get Conversation Activities request and response. La respuesta Obtener actividades de conversación contiene watermark como propiedad de ActivitySet.The Get Conversation Activities response contains watermark as a property of the ActivitySet. Los clientes deben desplazarse por las actividades disponibles haciendo avanzar el valor watermark hasta que no se devuelvan actividades.Clients should page through the available activities by advancing the watermark value until no activities are returned.

SolicitudRequest

GET https://directline.botframework.com/v3/directline/conversations/abc123/activities?watermark=0001a-94
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0

ResponseResponse

HTTP/1.1 200 OK
[other headers]
{
    "activities": [
        {
            "type": "message",
            "channelId": "directline",
            "conversation": {
                "id": "abc123"
            },
            "id": "abc123|0000",
            "from": {
                "id": "user1"
            },
            "text": "hello"
        }, 
        {
            "type": "message",
            "channelId": "directline",
            "conversation": {
                "id": "abc123"
            },
            "id": "abc123|0001",
            "from": {
                "id": "bot1"
            },
            "text": "Nice to see you, user1!"
        }
    ],
    "watermark": "0001a-95"
}

Consideraciones de tiempoTiming considerations

La mayoría de los clientes desean conservar un historial completo de mensajes.Most clients wish to retain a complete message history. Aunque Direct Line es un protocolo de varias partes con posibles diferencias temporales, el protocolo y el servicio están diseñados para que sea fácil crear un cliente confiable.Even though Direct Line is a multi-part protocol with potential timing gaps, the protocol and service is designed to make it easy to build a reliable client.

  • La propiedad watermark que se envía en la secuencia de WebSocket y en la respuesta de Obtener actividades de conversación es confiable.The watermark property that is sent in the WebSocket stream and Get Conversation Activities response is reliable. Un cliente no perderá ningún mensaje siempre que se reproduzca la marca de agua textualmente.A client will not miss any messages as long as it replays the watermark verbatim.

  • Cuando un cliente inicia una conversación y se conecta a la secuencia de WebSocket, las actividades que se envían después de POST, pero antes de que se abra el socket, se reproducen antes que las nuevas actividades.When a client starts a conversation and connects to the WebSocket stream, any activities that are sent after the POST but before the socket is opened are replayed before new activities.

  • Cuando un cliente emite una solicitud Obtener actividades de conversación (para actualizar el historial) mientras se conecta a la secuencia de WebSocket, las actividades pueden estar duplicadas en ambos canales.When a client issues a Get Conversation Activities request (to refresh history) while it is connected to the WebSocket stream, activities may be duplicated across both channels. Los clientes deben mantener el seguimiento de todos los identificadores de actividad conocidos para que puedan rechazar las actividades duplicadas, en caso de producirse.Clients should keep track of all known activity IDs so that they are able to reject duplicate activities, should they occur.

Los clientes que sondean con HTTP GET deben elegir un intervalo de sondeo que coincida con su uso previsto.Clients that poll using HTTP GET should choose a polling interval that matches their intended use.

  • Las aplicaciones de servicio a servicio suelen usar un intervalo de sondeo de 5 o 10 s.Service-to-service applications often use a polling interval of 5s or 10s.

  • Las aplicaciones orientadas al cliente a menudo usan un intervalo de sondeo de 1 segundo y emiten una única solicitud adicional poco después de cada mensaje que envía el cliente (para recuperar rápidamente la respuesta de un bot).Client-facing applications often use a polling interval of 1s, and issue a single additional request shortly after every message that the client sends (to rapidly retrieve a bot's response). La duración mínima de este retraso puede ser de 300 ms, pero se debe ajustar según el tiempo de tránsito y la velocidad del bot.This delay can be as short at 300ms but should be tuned based on the bot's speed and transit time. El sondeo no debe tener una frecuencia superior a una vez por segundo durante cualquier período de tiempo prolongado.Polling should not be more frequent than once per second for any extended period of time.

Recursos adicionalesAdditional resources