Ricevere attività dal bot nell'API Direct Line 3.0

Articolo
03/08/2023

Usando il protocollo Direct Line 3.0, i client possono ricevere attività tramite il flusso WebSocket o recuperare attività inviando richieste HTTP GET.

WebSocket e HTTP GET

Un WebSocket di streaming esegue in modo efficiente il push dei messaggi ai client, mentre l'interfaccia GET consente ai client di richiedere in modo esplicito i messaggi. Anche se il meccanismo basato su WebSocket è spesso preferibile per la sua efficacia, il meccanismo basato su GET può essere utile per i client che non riescono a usare i WebSocket.

Il servizio consente solo una connessione WebSocket per conversazione. Direct Line può chiudere altre connessioni WebSocket con un valore del motivo di collision.

Non tutti i tipi di attività sono disponibili sia tramite WebSocket che tramite HTTP GET. La tabella seguente descrive la disponibilità dei vari tipi di attività per i client che usano il protocollo Direct Line.

Tipo di attività	Disponibilità
message	HTTP GET e WebSocket
typing	Solo WebSocket
conversationUpdate	Non inviata/ricevuta tramite client
contactRelationUpdate	Non supportata in Direct Line
endOfConversation	HTTP GET e WebSocket
tutti gli altri tipi di attività	HTTP GET e WebSocket

Ricevere attività tramite un flusso WebSocket

Quando un client invia una richiesta di avvio di conversazione per aprire una conversazione con un bot, la risposta del servizio include una proprietà streamUrl che il client può successivamente usare per connettersi tramite WebSocket. L'URL del flusso è preautorizzato e quindi la richiesta del client di connettersi tramite WebSocket NON richiede un'intestazione Authorization.

L'esempio seguente illustra una richiesta che usa una proprietà streamUrl per connettersi tramite WebSocket.

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

Il servizio risponde con il codice di stato HTTP 101 ("Passaggio da un protocollo all'altro").

HTTP/1.1 101 Switching Protocols
[other headers]

Ricevere messaggi

Dopo la connessione tramite WebSocket, un client può ricevere questi tipi di messaggi dal servizio Direct Line:

Un messaggio contenente un oggetto ActivitySet che include una o più attività e una filigrana (descritto sotto).
Un messaggio vuoto, usato dal servizio Direct Line per verificare che la connessione sia ancora valida.
Tipi aggiuntivi, da definire in un secondo momento. Questi tipi vengono identificati dalle proprietà nella radice JSON.

Un oggetto ActivitySet contiene i messaggi inviati dal bot e da tutti gli utenti della conversazione. L'esempio seguente illustra un oggetto ActivitySet contenente un singolo messaggio.

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

Elaborare i messaggi

Un client deve tenere traccia del valore di watermark che riceve in ogni ActivitySet, per poter usare la filigrana per garantire che nessun messaggio vada perso se perde la connessione e deve riconnettersi alla conversazione. Se il client riceve un oggetto ActivitySet in cui la proprietà watermark è null o mancante, deve ignorare tale valore e non sovrascrivere la filigrana precedente ricevuta.

Un client deve ignorare i messaggi vuoti che riceve dal servizio Direct Line.

Un client può inviare messaggi vuoti al servizio Direct Line per verificare la connettività. Il servizio Direct Line ignorerà i messaggi vuoti che riceve dal client.

Il servizio Direct Line potrebbe chiudere forzatamente la connessione WebSocket in determinate condizioni. Se il client non ha ricevuto un'attività endOfConversation, potrebbe generare un nuovo URL di flusso WebSocket da usare per riconnettersi alla conversazione.

Il flusso WebSocket contiene aggiornamenti live e messaggi molto recenti (poiché la chiamata per connettersi tramite WebSocket è stata rilasciata), ma non include messaggi inviati prima dell'ultima POST a /v3/directline/conversations/{id}. Per recuperare i messaggi inviati in precedenza nella conversazione, usare HTTP GET, come illustrato sotto.

Recuperare le attività con HTTP GET

I client che non sono in grado di usare WebSocket possono recuperare le attività tramite HTTP GET.

Per recuperare i messaggi di una conversazione specifica, inviare una richiesta GET all'endpoint /v3/directline/conversations/{conversationId}/activities, specificando facoltativamente il parametro watermark per il messaggio più recente visualizzato dal client.

I frammenti seguenti offrono un esempio della richiesta di acquisizione delle attività della conversazione e della risposta. La risposta all'acquisizione delle attività della conversazione contiene watermark come proprietà di ActivitySet. Per scorrere le attività disponibili, i client dovranno far avanzare il valore di watermark fino a quando non viene restituita alcuna attività.

Richiesta

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

Risposta

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

Considerazioni sulla temporizzazione

La maggior parte dei client vuole conservare una cronologia dei messaggi completa. Anche se Direct Line è un protocollo multiparte con potenziali interruzioni nella temporizzazione, il protocollo e il servizio sono progettati per facilitare la compilazione di un client affidabile.

La proprietà watermark inviata nel flusso di WebSocket e la risposta all'acquisizione delle attività della conversazione sono affidabili. Un client non perderà alcun messaggio finché riproduce il limite verbatim.
Quando un client avvia una conversazione e si connette al flusso di WebSocket, le attività inviate dopo l'operazione POST, ma prima dell'apertura del socket, vengono riprodotte prima delle nuove attività.
Quando un client invia una richiesta Get Conversation Activities (per aggiornare la cronologia) mentre è connessa al flusso WebSocket, le attività possono essere duplicate in entrambi i canali. I client devono tenere traccia di tutti gli ID attività noti in modo che siano in grado di rifiutare le attività duplicate, qualora si verifichino.

I client che eseguono il polling usando HTTP GET devono scegliere un intervallo di polling che corrisponde all'uso previsto.

Le applicazioni da servizio a servizio usano spesso un intervallo di polling di 5 o 10 secondi.
Le applicazioni per i client usano spesso un intervallo di polling di 1 secondo e inviano una richiesta aggiuntiva poco dopo ogni messaggio inviato dal client, per recuperare rapidamente la risposta di un bot. Questo ritardo può essere di 300 ms, ma deve essere impostato in base alla velocità e al tempo di transito del robot. Il polling non deve essere più frequente di una volta al secondo per un lungo periodo di tempo.

Condividi tramite