Démarrer une conversation dans Direct Line API 3.0

  • Article

Les conversations Direct Line sont explicitement ouvertes par les clients et peuvent durer tant que le robot et le client y participent et tant que leurs informations d’identification sont valides. La conversation étant ouverte, le robot et le client peuvent envoyer des messages. Plusieurs clients peuvent se connecter à une conversation donnée, et chaque client peut participer pour le compte de plusieurs utilisateurs.

Ouvrir une nouvelle conversation

Pour démarrer une nouvelle conversation à partir de votre client, émettez POST sur le point de terminaison /v3/directline/conversations.

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

Les extraits de code suivants fournissent un exemple de demande et de réponse de la conversation de démarrage.

Requête

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

response

Si la requête aboutit, la réponse contient un ID pour la conversation, un jeton, une valeur indiquant le nombre de secondes avant l’expiration du jeton et une URL de flux que le client peut utiliser pour recevoir des activités par le biais du flux WebSocket.

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

En règle générale, une demande de démarrage de conversation est utilisée pour ouvrir une nouvelle conversation et un code d’état HTTP 201 est retourné si la nouvelle conversation est démarrée avec succès. Toutefois, si un client envoie une demande de conversation de démarrage avec un jeton de Direct Line dans l’en-tête Authorization utilisé précédemment pour démarrer une conversation à l’aide de l’opération de démarrage de la conversation, un code d’état HTTP 200 est retourné pour indiquer que la demande était acceptable mais qu’aucune conversation n’a été créée (comme elle existait déjà).

Conseil

Vous disposez de 60 secondes pour vous connecter à l’URL de flux WebSocket. Si la connexion ne peut pas être établie pendant ce temps, vous pouvez vous reconnecter à la conversation pour générer une nouvelle URL de flux.

Démarrer la conversation et générer un jeton

L’opération de conversation de démarrage (POST /v3/directline/conversations) est similaire à l’opération de génération de jeton (POST /v3/directline/tokens/generate) dans laquelle les deux opérations retournent un token qui peut être utilisé pour accéder à une seule conversation. Toutefois, l’opération de démarrage de la conversation démarre également la conversation, contacte le bot et crée une URL de flux WebSocket, tandis que l’opération de génération de jeton n’effectue aucune de ces opérations.

Si vous envisagez de démarrer la conversation immédiatement avec votre client, utilisez l’opération de démarrage de la conversation. Si vous envisagez de distribuer le jeton aux clients et que vous souhaitez qu’ils lancent la conversation, utilisez plutôt l’opération de génération de jeton .

Ressources supplémentaires