Creare un bot con il servizio Bot Connector con l'API Bot Connector

Articolo
10/07/2023

Il servizio Bot Connector consente al bot di scambiare messaggi con canali configurati nella portale di Azure, usando REST e JSON standard del settore tramite HTTPS. Questa esercitazione illustra il processo di acquisizione di un token di accesso dal Bot Framework e l'uso del servizio Bot Connector per lo scambio di messaggi con l'utente.

Ottenere un token di accesso

Importante

Se non è già stato fatto, è necessario registrare il bot con Bot Framework per ottenere l'ID e la password dell'app. Per ottenere un token di accesso, sarà necessario appID e password del bot.

Per comunicare con il servizio Bot Connector è necessario specificare un token di accesso nell'intestazione Authorization di ogni richiesta dell'API, usando questo formato:

Authorization: Bearer ACCESS_TOKEN

È possibile ottenere il token di accesso per il bot inviando una richiesta API.

Richiesta

Per richiedere un token di accesso che può essere usato per autenticare le richieste al servizio Bot Connector, inviare la seguente richiesta, sostituendo MICROSOFT-APP-ID e MICROSOFT-APP-PASSWORD con l'ID e la password dell'app ottenuti quando è stato registrato il bot con Bot Framework.

POST https://login.microsoftonline.com/botframework.com/oauth2/v2.0/token
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=MICROSOFT-APP-ID&client_secret=MICROSOFT-APP-PASSWORD&scope=https%3A%2F%2Fapi.botframework.com%2F.default

Risposta

Se la richiesta ha esito positivo, si riceverà una risposta HTTP 200 che specifica il token di accesso e le informazioni sulla relativa scadenza.

{
    "token_type":"Bearer",
    "expires_in":3600,
    "ext_expires_in":3600,
    "access_token":"eyJhbGciOiJIUzI1Ni..."
}

Suggerimento

Per altre informazioni sull'autenticazione nel servizio Bot Connector, vedere autenticazione.

Scambiare messaggi con l'utente

Una conversazione è una serie di messaggi scambiati tra un utente e il bot.

Ricevere un messaggio dall'utente

Quando l'utente invia un messaggio, Bot Framework Connector invia una richiesta all'endpoint specificato quando è stato registrato il bot. Il corpo della richiesta è un oggetto Attività. L'esempio seguente illustra il corpo della richiesta che un bot riceve quando l'utente invia un messaggio semplice al bot.

{
    "type": "message",
    "id": "bf3cc9a2f5de...",
    "timestamp": "2016-10-19T20:17:52.2891902Z",
    "serviceUrl": "https://smba.trafficmanager.net/teams",
    "channelId": "channel's name/id",
    "from": {
        "id": "1234abcd",
        "name": "user's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
    },
    "recipient": {
        "id": "12345678",
        "name": "bot's name"
    },
    "text": "Haircut on Saturday"
}

Rispondere al messaggio dell'utente

Quando l'endpoint del bot riceve una richiesta che rappresenta un POST messaggio dall'utente (ad esempio, type = messaggio), usare le informazioni contenute in tale richiesta per creare l'oggetto Activity per la risposta.

Impostare la proprietà conversation sul contenuto della proprietà conversation nel messaggio dell'utente.
Impostare la proprietà from sul contenuto della proprietà recipient nel messaggio dell'utente.
Impostare la proprietà recipient sul contenuto della proprietà from nel messaggio dell'utente.
Impostare le proprietà text e attachments in modo appropriato.

Usare la proprietà serviceUrl nella richiesta in ingresso per identificare l'URI di base che il bot deve usare per inviare la risposta.

Per inviare la risposta, eseguire il POST dell'oggetto Activity su /v3/conversations/{conversationId}/activities/{activityId}, come illustrato nell'esempio seguente. Il corpo della richiesta è un oggetto Activity che richiede all'utente di selezionare un orario di appuntamento disponibile. 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/bf3cc9a2f5de... 
Authorization: Bearer eyJhbGciOiJIUzI1Ni...
Content-Type: application/json

{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "bot's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
   },
   "recipient": {
        "id": "1234abcd",
        "name": "user's name"
    },
    "text": "I have these times available:",
    "replyToId": "bf3cc9a2f5de..."
}

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.

Importante

Come illustrato in questo esempio, l'intestazione Authorization di ogni richiesta API inviata deve contenere la parola Bearer seguita dal token di accesso ottenuto dal Bot Framework.

Per inviare un altro messaggio che consente a un utente di selezionare un orario di appuntamento disponibile facendo clic su un pulsante, eseguire il POST di un'altra richiesta allo stesso endpoint:

POST https://smba.trafficmanager.net/teams/v3/conversations/abcd1234/activities/bf3cc9a2f5de... 
Authorization: Bearer eyJhbGciOiJIUzI1Ni...
Content-Type: application/json

{
    "type": "message",
    "from": {
        "id": "12345678",
        "name": "bot's name"
    },
    "conversation": {
        "id": "abcd1234",
        "name": "conversation's name"
   },
   "recipient": {
        "id": "1234abcd",
        "name": "user's name"
    },
    "attachmentLayout": "list",
    "attachments": [
      {
        "contentType": "application/vnd.microsoft.card.thumbnail",
        "content": {
          "buttons": [
            {
              "type": "imBack",
              "title": "10:30",
              "value": "10:30"
            },
            {
              "type": "imBack",
              "title": "11:30",
              "value": "11:30"
            },
            {
              "type": "openUrl",
              "title": "See more",
              "value": "http://www.contososalon.com/scheduling"
            }
          ]
        }
      }
    ],
    "replyToId": "bf3cc9a2f5de..."
}

Passaggi successivi

In questa esercitazione è stato ottenuto un token di accesso dal Bot Framework ed è stato usato il servizio Bot Connector per lo scambio di messaggi con l'utente. È possibile usare Bot Framework Emulator per eseguire il test e il debug del bot. Se si vuole condividere il bot con altri utenti, è necessario configurarlo per l'esecuzione in uno o più canali.