Inviare e ricevere messaggi con l'API Bot Connector
Il servizio Bot Connector consente a un bot di comunicare tramite più canali, ad esempio posta elettronica, Slack e altri ancora. Facilita la comunicazione tra bot e utente, inoltrando le attività dal bot al canale e dal canale al bot. Ogni attività contiene informazioni usate per il routing del messaggio alla destinazione appropriata, oltre a informazioni sull'utente che ha creato il messaggio, sul contesto del messaggio e sul destinatario del messaggio. Questo articolo descrive come usare il servizio Bot Connector per scambiare le attività del messaggio tra il bot e l'utente in un canale.
Rispondere a un messaggio
Creare una risposta
Quando l'utente invia un messaggio al bot, il bot riceve il messaggio come oggetto Attività di tipo message. Per creare una risposta al messaggio di un utente, creare un nuovo oggetto Activity e impostare queste proprietà:
| Proprietà | Valore |
|---|---|
| conversazione | Impostare questa proprietà sui contenuti della proprietà conversation nel messaggio dell'utente. |
| da | Impostare questa proprietà sui contenuti della proprietà recipient nel messaggio dell'utente. |
| locale | Impostare questa proprietà sui contenuti della proprietà locale nel messaggio dell'utente, se specificati. |
| recipient | Impostare questa proprietà sui contenuti della proprietà from nel messaggio dell'utente. |
| replyToId | Impostare questa proprietà sui contenuti della proprietà id nel messaggio dell'utente. |
| type | Impostare questa proprietà su message. |
Impostare quindi le proprietà che specificano le informazioni che si vuole comunicare all'utente. È ad esempio possibile impostare la proprietà text per specificare il testo da visualizzare nel messaggio, impostare la proprietà speak per specificare il testo che deve essere pronunciato dal bot nel messaggio e impostare la proprietà attachments per specificare gli allegati multimediali o le schede avanzate da includere nel messaggio. Per informazioni dettagliate sulle proprietà dei messaggi di uso comune, vedere Creare messaggi.
Inviare la risposta
Usare la proprietà serviceUrl nell'attività in ingresso per identificare l'URI di base che il bot deve usare per inviare la risposta.
Per inviare la risposta, eseguire questa richiesta:
POST /v3/conversations/{conversationId}/activities/{activityId}
In questo URI di richiesta sostituire {conversationId} con il valore della proprietà id dell'oggetto conversation nell'attività (di risposta) e sostituire {activityId} con il valore della proprietà replyToId nell'attività (di risposta). Impostare il corpo della richiesta sull'oggetto Attività creato per rappresentare la risposta.
L'esempio seguente illustra una richiesta che invia una semplice risposta di solo testo al messaggio di un utente. In questa richiesta di esempio https://smba.trafficmanager.net/teams rappresenta l'URI di base. L'URI di base per le richieste inviate dal bot può essere diverso. Per informazioni dettagliate sull'impostazione dell'URI di base, vedere Informazioni di riferimento sulle API.
POST https://smba.trafficmanager.net/teams/v3/conversations/abcd1234/activities/5d5cdc723
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{
"type": "message",
"from": {
"id": "12345678",
"name": "Pepper's News Feed"
},
"conversation": {
"id": "abcd1234",
"name": "Convo1"
},
"recipient": {
"id": "1234abcd",
"name": "SteveW"
},
"text": "My bot's reply",
"replyToId": "5d5cdc723"
}
Inviare un messaggio (non-risposta)
La maggior parte dei messaggi inviati dal bot sarà in risposta a messaggi ricevuti dall'utente. In alcuni casi, tuttavia, il bot deve inviare un messaggio alla conversazione che non è una risposta diretta ad alcun messaggio dell'utente. Potrebbe ad esempio essere necessario che il bot inizi un nuovo argomento di conversazione o invii un messaggio di chiusura alla fine della conversazione.
Per inviare un messaggio a una conversazione che non è una risposta diretta ad alcun messaggio dell'utente, inviare questa richiesta:
POST /v3/conversations/{conversationId}/activities
In questo URI di richiesta sostituire {conversationId} con l'ID della conversazione.
Impostare il corpo della richiesta su un oggetto Attività creato per rappresentare la risposta.
Nota
Bot Framework non impone alcuna restrizione sul numero di messaggi che un bot può inviare. La maggior parte dei canali impone tuttavia limitazioni della larghezza di banda della rete per impedire ai bot di inviare un numero elevato di messaggi in un breve periodo di tempo. Se il bot invia inoltre più messaggi in rapida successione, è possibile che il canale non esegua sempre il rendering dei messaggi nella sequenza corretta.
Avviare una conversazione
Potrebbe essere talvolta necessario che il bot avvii una conversazione con uno o più utenti. Per avviare una conversazione con un utente in un canale, il bot deve conoscere le proprie informazioni account e le informazioni account dell'utente in tale canale.
Suggerimento
Nell'eventualità che il bot debba avviare conversazioni con gli utenti in futuro, memorizzare nella cache le informazioni account utente, altre informazioni rilevanti, ad esempio le preferenze dell'utente e le impostazioni locali, e l'URL del servizio (da usare come URI di base nella richiesta di avvio della conversazione).
Per avviare una conversazione, inviare questa richiesta:
POST /v3/conversations
Impostare il corpo della richiesta su un oggetto ConversationParameters che specifica le informazioni account del bot e le informazioni account degli utenti da includere nella conversazione.
Nota
Non tutti i canali supportano le conversazioni di gruppo. Consultare la documentazione del canale per determinare se un canale supporta le conversazioni di gruppo e per identificare il numero massimo di partecipanti consentiti in una conversazione da un canale.
Il seguente esempio mostra una richiesta che avvia una conversazione. In questa richiesta di esempio https://smba.trafficmanager.net/teams rappresenta l'URI di base. L'URI di base per le richieste inviate dal bot può essere diverso. Per informazioni dettagliate sull'impostazione dell'URI di base, vedere Informazioni di riferimento sulle API.
POST https://smba.trafficmanager.net/teams/v3/conversations
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{
"bot": {
"id": "12345678",
"name": "bot's name"
},
"isGroup": false,
"members": [
{
"id": "1234abcd",
"name": "recipient's name"
}
],
"topicName": "News Alert"
}
Se viene stabilita la conversazione con gli utenti specificati, la risposta conterrà un ID che identifica la conversazione.
{
"id": "abcd1234"
}
Il bot può quindi usare l'ID della conversazione per inviare un messaggio agli utenti nella conversazione.