Activiteiten ontvangen van de bot in Direct Line API 3.0

Artikel
03/08/2023

Met behulp van het Direct Line 3.0-protocol kunnen clients activiteiten ontvangen via WebSocket stream of activiteiten ophalen door aanvragen uit te gevenHTTP GET.

WebSocket versus HTTP GET

Een streaming WebSocket pusht berichten efficiënt naar clients, terwijl de GET-interface clients in staat stelt om expliciet berichten op te vragen. Hoewel het WebSocket-mechanisme vaak de voorkeur heeft vanwege de efficiëntie, kan het GET-mechanisme nuttig zijn voor clients die geen WebSockets kunnen gebruiken.

De service staat slechts 1 WebSocket-verbinding per gesprek toe. Direct Line kunnen extra WebSocket-verbindingen sluiten met een redenwaarde van collision.

Niet alle activiteitstypen zijn zowel via WebSocket als via HTTP GET beschikbaar. In de volgende tabel wordt de beschikbaarheid van de verschillende activiteitstypen beschreven voor clients die gebruikmaken van het Direct Line-protocol.

Type activiteit	Beschikbaarheid
message	HTTP GET en WebSocket
Typen	Alleen WebSocket
conversationUpdate	Niet verzonden/ontvangen via client
contactRelationUpdate	Niet ondersteund in Direct Line
endOfConversation	HTTP GET en WebSocket
alle andere activiteitstypen	HTTP GET en WebSocket

Activiteiten ontvangen via WebSocket-stream

Wanneer een client een aanvraag gesprek starten verzendt om een gesprek met een bot te openen, bevat het antwoord van de service een streamUrl eigenschap die de client vervolgens kan gebruiken om verbinding te maken via WebSocket. De stream-URL is vooraf geverifieerd en daarom is voor de aanvraag van de client om verbinding te maken via WebSocket GEEN header vereist Authorization .

In het volgende voorbeeld ziet u een aanvraag die gebruikmaakt van een streamUrl om verbinding te maken via WebSocket.

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

De service reageert met statuscode HTTP 101 ('Switching Protocols').

HTTP/1.1 101 Switching Protocols
[other headers]

Berichten ontvangen

Nadat er verbinding is gemaakt via WebSocket, kan een client deze typen berichten ontvangen van de Direct Line-service:

Een bericht dat een ActivitySet bevat met een of meer activiteiten en een watermerk (hieronder beschreven).
Een leeg bericht dat door de Direct Line-service wordt gebruikt om ervoor te zorgen dat de verbinding nog steeds geldig is.
Aanvullende typen, die later worden gedefinieerd. Deze typen worden geïdentificeerd door de eigenschappen in de JSON-hoofdmap.

Een ActivitySet bevat berichten die zijn verzonden door de bot en door alle gebruikers in het gesprek. In het volgende voorbeeld ziet u een ActivitySet met één bericht.

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

Berichten verwerken

Een client moet de watermark waarde bijhouden die deze ontvangt in elke ActivitySet, zodat deze het watermerk kan gebruiken om te garanderen dat er geen berichten verloren gaan als de verbinding wordt verbroken en opnieuw verbinding moet maken met het gesprek. Als de client een ActivitySet waarde ontvangt waarin de watermark eigenschap is null of ontbreekt, moet deze die waarde negeren en het voorgaande watermerk dat hij heeft ontvangen, niet overschrijven.

Een client moet lege berichten negeren die deze ontvangt van de Direct Line-service.

Een client kan lege berichten verzenden naar de Direct Line-service om de connectiviteit te controleren. De Direct Line-service negeert lege berichten die van de client worden ontvangen.

De Direct Line-service kan de WebSocket-verbinding onder bepaalde voorwaarden geforceerd sluiten. Als de client geen activiteit heeft ontvangen endOfConversation , kan deze een nieuwe WebSocket-stream-URL genereren die kan worden gebruikt om opnieuw verbinding te maken met het gesprek.

De WebSocket-stream bevat live-updates en zeer recente berichten (omdat de aanroep om verbinding te maken via WebSocket is verzonden), maar bevat geen berichten die zijn verzonden vóór de meest recente POST naar /v3/directline/conversations/{id}. Als u berichten wilt ophalen die eerder in het gesprek zijn verzonden, gebruikt HTTP GET u zoals hieronder wordt beschreven.

Activiteiten ophalen met HTTP GET

Clients die geen WebSockets kunnen gebruiken, kunnen activiteiten ophalen met behulp van HTTP GET.

Als u berichten voor een specifiek gesprek wilt ophalen, verzendt u een GET aanvraag naar het /v3/directline/conversations/{conversationId}/activities eindpunt, optioneel geeft u de watermark parameter op om het meest recente bericht aan te geven dat door de client is gezien.

De volgende fragmenten bieden een voorbeeld van de aanvraag en het antwoord Gespreksactiviteiten ophalen. Het antwoord Gespreksactiviteiten ophalen bevat watermark als eigenschap van de ActivitySet. Clients moeten door de beschikbare activiteiten bladeren door de watermark waarde door te voeren totdat er geen activiteiten worden geretourneerd.

Aanvraag

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

Antwoord

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

Timingoverwegingen

De meeste clients willen een volledige berichtgeschiedenis behouden. Hoewel Direct Line een meerdelig protocol is met mogelijke tijdsverschillen, zijn het protocol en de service ontworpen om het eenvoudig te maken om een betrouwbare client te bouwen.

De watermark eigenschap die wordt verzonden in de WebSocket-stream en het antwoord Gespreksactiviteiten ophalen is betrouwbaar. Een client mist geen berichten zolang de exacte bewoordingen van het watermerk opnieuw worden afgespeeld.
Wanneer een client een gesprek start en verbinding maakt met de WebSocket-stream, worden alle activiteiten die na post worden verzonden, maar voordat de socket wordt geopend, opnieuw afgespeeld vóór nieuwe activiteiten.
Wanneer een client een aanvraag gespreksactiviteiten ophalen uitgeeft (om de geschiedenis te vernieuwen) terwijl deze is verbonden met de WebSocket-stream, kunnen activiteiten in beide kanalen worden gedupliceerd. Clients moeten alle bekende activiteits-id's bijhouden, zodat ze dubbele activiteiten kunnen weigeren als deze zich voordoen.

Clients die polls gebruiken, HTTP GET moeten een polling-interval kiezen dat overeenkomt met het beoogde gebruik.

Service-naar-servicetoepassingen gebruiken vaak een polling-interval van 5s of 10s.
Clientgerichte toepassingen gebruiken vaak een polling-interval van 1s en geven kort na elk bericht dat de client verzendt één extra aanvraag uit (om snel het antwoord van een bot op te halen). Deze vertraging kan 300 ms even kort zijn, maar moet worden afgestemd op basis van de snelheid en transittijd van de bot. Polling mag gedurende een langere periode niet vaker dan één keer per seconde voorkomen.

Delen via