Inviare un'attività al bot in Direct Line'API 3.0
Tramite il protocollo Direct Line 3.0, client e bot possono scambiare diversi tipi di attività, tra cui attività di messaggio, di digitazione e personalizzate supportate dal bot. I client possono inviare un'unica attività per richiesta.
Inviare un'attività
Per inviare un'attività al bot, il client deve creare un oggetto Attività per definire l'attività e quindi inoltrare una richiesta POST a https://directline.botframework.com/v3/directline/conversations/{conversationId}/activities, specificando l'oggetto Attività nel corpo della richiesta.
I frammenti di codice seguenti offrono un esempio della richiesta di invio dell'attività e della risposta.
Richiesta
POST https://directline.botframework.com/v3/directline/conversations/abc123/activities
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: application/json
[other headers]
{
"locale": "en-EN",
"type": "message",
"from": {
"id": "user1"
},
"text": "hello"
}
Risposta
Quando l'attività viene recapitata al bot, il servizio risponde con un codice di stato HTTP che riflette il codice di stato del bot. Se il bot genera un errore, viene restituita una risposta HTTP 502, "Gateway non valido", al client in risposta alla richiesta di invio dell'attività.
Nota
Ciò può essere causato dal fatto che non è stato usato un token corretto. Per inviare un'attività, può essere usato solo il token ricevuto per avviare la conversazione.
Se il POST ha esito positivo, la risposta contiene un payload JSON che specifica l'ID dell'attività inviato al bot.
HTTP/1.1 200 OK
[other headers]
{
"id": "0001"
}
Tempo totale per la richiesta/risposta di invio dell'attività
Il tempo totale necessario per PUBBLICARE un messaggio in una conversazione Direct Line è la somma delle operazioni seguenti:
- Tempo di transito che la richiesta HTTP impiega per essere trasferita dal client al servizio Direct Line
- Tempo di elaborazione interna in Direct Line, in genere inferiore a 120 ms
- Tempo di transito dal servizio Direct Line al bot
- Tempo di elaborazione nel bot
- Tempo di transito necessario alla risposta HTTP per essere restituita al client
Inviare allegati al bot
In alcuni casi è possibile che un client debba inviare allegati al bot, ad esempio immagini o documenti. Un client può inviare allegati al bot specificando gli URL degli allegati nell'oggetto Attività che invia tramite POST /v3/directline/conversations/{conversationId}/activities o caricando gli allegati usando POST /v3/directline/conversations/{conversationId}/upload.
Inviare allegati tramite URL
Per inviare uno o più allegati come parte dell'oggetto Attività tramite POST /v3/directline/conversations/{conversationId}/activities, è sufficiente includere uno o più oggetti Allegato all'interno dell'oggetto Attività e impostare la proprietà contentUrl di ogni oggetto Allegato per specificare il protocollo HTTP, HTTPS, o URI data dell'allegato.
Inviare allegati tramite caricamento
Spesso un client contiene immagini o documenti in un dispositivo che desidera inviare al bot, ma non contiene gli URL corrispondenti a questi file. In questo caso un client può inoltrare una richiesta POST /v3/directline/conversations/{conversationId}/upload per inviare gli allegati al bot tramite caricamento. Il formato e i contenuti della richiesta variano a seconda del fatto che il client invia un solo allegato oppure invia più allegati.
Inviare un solo allegato tramite caricamento
Per inviare un solo allegato tramite caricamento, inoltrare questa richiesta:
POST https://directline.botframework.com/v3/directline/conversations/{conversationId}/upload?userId={userId}
Authorization: Bearer SECRET_OR_TOKEN
Content-Type: TYPE_OF_ATTACHMENT
Content-Disposition: ATTACHMENT_INFO
[other headers]
[file content]
In questo URI della richiesta, sostituire {conversationId} con l'ID della conversazione e {userId} con l'ID dell'utente che invia il messaggio. Il parametro userId è obbligatorio. Nelle intestazioni della richiesta impostare Content-Type per specificare il tipo di allegato e impostare Content-Disposition per specificare il nome del file dell'allegato.
I frammenti di codice seguenti offrono un esempio della richiesta di invio di un solo allegato e della risposta.
Richiesta
POST https://directline.botframework.com/v3/directline/conversations/abc123/upload?userId=user1
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: image/jpeg
Content-Disposition: name="file"; filename="badjokeeel.jpg"
[other headers]
[JPEG content]
Risposta
Se la richiesta ha esito positivo, un'Attività messaggio viene inviata al bot quando viene completato il caricamento. La risposta che il client riceve conterrà l'ID dell'attività che è stato inviato.
HTTP/1.1 200 OK
[other headers]
{
"id": "0003"
}
Inviare più allegati tramite caricamento
Per inviare più allegati tramite caricamento, pubblicare con POST una richiesta multipart nell'endpoint /v3/directline/conversations/{conversationId}/upload. Impostare l'intestazione della richiesta Content-Type in multipart/form-data e includere le intestazioni Content-Type e Content-Disposition per ogni parte per specificare il tipo e il nome del file di ogni allegato. Nell'URI della richiesta impostare il parametro userId nell'ID dell'utente che invia il messaggio.
È possibile includere un oggetto Activity nella richiesta aggiungendo una parte che specifica il valore application/vnd.microsoft.activity dell'intestazione Content-Type. Se la richiesta include un'attività, gli allegati specificati da altre parti del payload vengono aggiunti come allegati a tale attività prima dell'invio. Se la richiesta non include un'attività, viene creata un'attività vuota per fungere da contenitore in cui vengono inviati gli allegati specificati.
I frammenti di codice seguenti offrono un esempio della richiesta di invio di più allegati e della risposta. In questo esempio la richiesta invia un messaggio che contiene testo e un allegato con una sola immagine. È stato possibile aggiungere parti aggiuntive alla richiesta per includere più allegati nel messaggio.
Richiesta
POST https://directline.botframework.com/v3/directline/conversations/abc123/upload?userId=user1
Authorization: Bearer RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0
Content-Type: multipart/form-data; boundary=----DD4E5147-E865-4652-B662-F223701A8A89
[other headers]
----DD4E5147-E865-4652-B662-F223701A8A89
Content-Type: image/jpeg
Content-Disposition: form-data; name="file"; filename="badjokeeel.jpg"
[other headers]
[JPEG content]
----DD4E5147-E865-4652-B662-F223701A8A89
Content-Type: application/vnd.microsoft.activity
[other headers]
{
"type": "message",
"from": {
"id": "user1"
},
"text": "Hey I just IM'd you\n\nand this is crazy\n\nbut here's my webhook\n\nso POST me maybe"
}
----DD4E5147-E865-4652-B662-F223701A8A89
Risposta
Se la richiesta ha esito positivo, un'Attività messaggio viene inviata al bot quando viene completato il caricamento. La risposta che il client riceve conterrà l'ID dell'attività che è stato inviato.
HTTP/1.1 200 OK
[other headers]
{
"id": "0004"
}