Receber atividades do bot em Direct Line API 3.0

Artigo
10/09/2024

Utilizando o protocolo Direct Line 3.0, os clientes podem receber atividades através de WebSocket stream ou recuperação através da emissão de HTTP GET pedidos.

WebSocket vs HTTP GET

Um streaming WebSocket empurra eficientemente mensagens para os clientes, enquanto a interface GET permite que os clientes solicitem explicitamente mensagens. Embora o mecanismo WebSocket seja muitas vezes preferido devido à sua eficiência, o mecanismo GET pode ser útil para clientes que não conseguem usar WebSockets.

O serviço permite apenas 1 ligação WebSocket por conversação. Direct Line pode fechar ligações webSocket adicionais com um valor de razão de collision.

Nem todos os tipos de atividade estão disponíveis tanto via WebSocket como via HTTP GET. A tabela seguinte descreve a disponibilidade dos vários tipos de atividade para clientes que utilizam o protocolo Direct Line.

Tipo de atividade	Disponibilidade
message	HTTP GET e WebSocket
dactilografia	Apenas WebSocket
conversaTodate	Não enviado/recebido via cliente
contactoRelationUpdate	Não apoiado em Direct Line
finalOfConversação	HTTP GET e WebSocket
todos os outros tipos de atividade	HTTP GET e WebSocket

Receber atividades através do stream WebSocket

Quando um cliente envia um pedido de Conversação Inicial para abrir uma conversa com um bot, a resposta do serviço inclui uma streamUrl propriedade que o cliente pode posteriormente usar para ligar via WebSocket. O URL de fluxo é pré-autorizado e, portanto, o pedido do cliente para se conectar via WebSocket NÃO requer um Authorization cabeçalho.

O exemplo a seguir mostra um pedido que usa um streamUrl para ligar via WebSocket.

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

O serviço responde com o código de estado HTTP 101 ("Protocolos de comutação").

HTTP/1.1 101 Switching Protocols
[other headers]

Receber mensagens

Depois de se ligar via WebSocket, um cliente pode receber este tipo de mensagens do serviço Direct Line:

Uma mensagem que contém um ActivitySet que inclui uma ou mais atividades e uma marca de água (descrita abaixo).
Uma mensagem vazia, que o serviço Direct Line utiliza para garantir que a ligação ainda é válida.
Tipos adicionais, a definir mais tarde. Estes tipos são identificados pelas propriedades na raiz JSON.

Um ActivitySet contém mensagens enviadas pelo bot e por todos os utilizadores na conversação. O exemplo a seguir mostra um ActivitySet que contém uma única mensagem.

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

Processar mensagens

Um cliente deve acompanhar o watermark valor que recebe em cada ActivitySet, para que possa utilizar a marca de água para garantir que não se perdem mensagens se perder a ligação e precisar de voltar a ligar-se à conversa. Se o cliente receber um ActivitySet em que o watermark imóvel está null ou em falta, deve ignorar esse valor e não substituir a marca de água anterior que recebeu.

Um cliente deve ignorar as mensagens vazias que recebe do serviço Direct Line.

Um cliente pode enviar mensagens vazias para o serviço Direct Line para verificar a conectividade. O serviço Direct Line ignorará as mensagens vazias que recebe do cliente.

O serviço Direct Line pode fechar à força a ligação WebSocket sob determinadas condições. Se o cliente não tiver recebido uma endOfConversation atividade, poderá gerar um novo URL de stream WebSocket que pode usar para voltar a ligar-se à conversa.

O stream WebSocket contém atualizações ao vivo e mensagens muito recentes (uma vez que a chamada para ligar via WebSocket foi emitida), mas não inclui mensagens que foram enviadas antes da mais recente POST para /v3/directline/conversations/{id}. Para recuperar mensagens enviadas anteriormente na conversa, use HTTP GET como descrito abaixo.

Recuperar atividades com HTTP GET

Os clientes que não conseguem utilizar webSockets podem recuperar atividades utilizando HTTP GET.

Para recuperar mensagens para uma conversação específica, emita um GET pedido ao /v3/directline/conversations/{conversationId}/activities ponto final, especificando opcionalmente o watermark parâmetro para indicar a mensagem mais recente vista pelo cliente.

Os seguintes snippets fornecem um exemplo do pedido e resposta de Get Conversation Activities. A resposta Get Conversation Activities contém watermark como propriedade do ActivitySet. Os clientes devem páginar através das atividades disponíveis, avançando o watermark valor até que nenhuma atividade seja devolvida.

Pedir

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

Resposta

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"
}

Considerações de tempo

A maioria dos clientes deseja manter um histórico completo de mensagens. Apesar de Direct Line ser um protocolo multi-partes com potenciais lacunas de tempo, o protocolo e o serviço são projetados para facilitar a construção de um cliente confiável.

A watermark propriedade que é enviada no stream WebSocket e obter resposta Desembals é fiável. Um cliente não perderá nenhuma mensagem desde que reproduza a marca de água verbatim.
Quando um cliente inicia uma conversação e se conecta ao stream WebSocket, quaisquer atividades que sejam enviadas após o POST mas antes da tomada ser aberta são reproduzidas antes de novas atividades.
Quando um cliente emite um pedido de Get Conversation Activities (para atualizar o histórico) enquanto está ligado ao stream WebSocket, as atividades podem ser duplicadas em ambos os canais. Os clientes devem acompanhar todas as iDs de atividade conhecidas para que possam rejeitar atividades duplicadas, caso ocorram.

Os clientes que usassem HTTP GET a sondagem devem escolher um intervalo de votação que corresponda ao seu uso pretendido.

As aplicações de serviço-a-serviço usam frequentemente um intervalo de votação de 5 s ou 10s.
As aplicações voltadas para o cliente usam frequentemente um intervalo de votação de 1s, e emitem um único pedido adicional pouco depois de cada mensagem que o cliente envia (para recuperar rapidamente a resposta de um bot). Este atraso pode ser tão curto a 300ms, mas deve ser afinado com base na velocidade e tempo de trânsito do bot. As sondagens não devem ser mais frequentes do que uma vez por segundo durante qualquer período de tempo prolongado.

Partilhar via