Avviare una conversazione in Direct Line API 3.0

  • Articolo

Le conversazioni Direct Line vengono aperte esplicitamente dai client e possono essere eseguite fintanto che il bot e il client partecipano e hanno credenziali valide. Mentre la conversazione è aperta, sia il bot che il client possono inviare messaggi. A una determinata conversazione possono connettersi più client e ognuno di essi può partecipare per conto di più utenti.

Aprire una nuova conversazione

Per aprire una nuova conversazione dal client, inviare una richiesta POST all'endpoint /v3/directline/conversations.

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

I frammenti seguenti forniscono un esempio della richiesta e della risposta della conversazione iniziale.

Richiesta

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

Risposta

Se la richiesta ha esito positivo, la risposta conterrà un ID per la conversazione, un token, un valore che indica il numero di secondi prima che il token scada e un URL di flusso che il client può usare per ricevere attività tramite un flusso 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..."
}

In genere, viene usata una richiesta di conversazione iniziale per aprire una nuova conversazione e viene restituito un codice di stato HTTP 201 se la nuova conversazione viene avviata correttamente. Tuttavia, se un client invia una richiesta di conversazione iniziale con un token di Direct Line nell'intestazione Authorization usata in precedenza per avviare una conversazione usando l'operazione di conversazione iniziale, verrà restituito un codice di stato HTTP 200 per indicare che la richiesta era accettabile ma non è stata creata alcuna conversazione (come già esistente).

Suggerimento

Si hanno 60 secondi per connettersi all'URL di flusso WebSocket. Se la connessione non può essere stabilita durante questa fase, è possibile riconnettersi alla conversazione per generare un nuovo URL di flusso.

Avviare la conversazione rispetto al token di generazione

L'operazione di conversazione iniziale () è simile all'operazione di generazione del token (POST /v3/directline/tokens/generatePOST /v3/directline/conversations) in cui entrambe le operazioni restituiscono un token oggetto che può essere usato per accedere a una singola conversazione. Tuttavia, l'operazione di conversazione iniziale avvia anche la conversazione, contatta il bot e crea un URL di flusso WebSocket, mentre l'operazione di generazione del token non esegue nessuna di queste operazioni.

Se si intende avviare immediatamente la conversazione con il client, usare l'operazione di conversazione iniziale. Se si prevede di distribuire il token ai client e di avviare la conversazione, usare invece l'operazione di generazione del token .

Risorse aggiuntive