Een gesprek starten in Direct Line API 3.0

Artikel
03/08/2023

Direct Line gesprekken worden expliciet geopend door clients en kunnen worden uitgevoerd zolang de bot en client deelnemen en geldige referenties hebben. Terwijl het gesprek is geopend, kunnen zowel de bot als de client berichten verzenden. Meerdere clients kunnen verbinding maken met een bepaald gesprek en elke client kan namens meerdere gebruikers deelnemen.

Een nieuw gesprek openen

Als u een nieuw gesprek van uw client wilt openen, geeft u POST uit naar het eindpunt /v3/directline/conversations.

POST https://directline.botframework.com/v3/directline/conversations
Authorization: Bearer SECRET_OR_TOKEN

De volgende codefragmenten bevatten een voorbeeld van de startgespreksaanvraag en het antwoord.

Aanvraag

POST https://directline.botframework.com/v3/directline/conversations
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn

Antwoord

Als de aanvraag is geslaagd, bevat het antwoord een id voor het gesprek, een token, een waarde die het aantal seconden aangeeft totdat het token verloopt en een stream-URL die de client kan gebruiken om activiteiten te ontvangen via WebSocket-stream.

HTTP/1.1 201 Created
[other headers]

{
  "conversationId": "abc123",
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 1800,
  "streamUrl": "https://directline.botframework.com/v3/directline/conversations/abc123/stream?t=RCurR_XV9ZA.cwA..."
}

Normaal gesproken wordt een startgespreksaanvraag gebruikt om een nieuw gesprek te openen en wordt een HTTP 201-statuscode geretourneerd als het nieuwe gesprek is gestart. Als een client echter een startgespreksaanvraag indient met een Direct Line token in de Authorization header die eerder is gebruikt om een gesprek te starten met behulp van de startgespreksbewerking, wordt er een HTTP 200-statuscode geretourneerd om aan te geven dat de aanvraag acceptabel was, maar er geen gesprek is gemaakt (zoals al bestond).

Tip

U hebt 60 seconden om verbinding te maken met de WebSocket-stream-URL. Als de verbinding gedurende deze tijd niet tot stand kan worden gebracht, kunt u opnieuw verbinding maken met het gesprek om een nieuwe stream-URL te genereren.

Gesprek starten versus token genereren

De startgespreksbewerking (POST /v3/directline/conversations) is vergelijkbaar met de bewerking voor het genereren van tokens (POST /v3/directline/tokens/generate) omdat beide bewerkingen een token bewerking retourneren die kan worden gebruikt voor toegang tot één gesprek. De startgespreksbewerking start echter ook het gesprek, neemt contact op met de bot en maakt een WebSocket-stream-URL, terwijl de bewerking voor het genereren van tokens geen van deze dingen doet.

Als u van plan bent om het gesprek onmiddellijk met uw client te starten, gebruikt u de startgespreksbewerking. Als u van plan bent om het token te distribueren naar clients en wilt dat ze het gesprek starten, gebruikt u in plaats daarvan de bewerking voor het genereren van tokens.

Delen via