Créer un bot avec le service Bot Connector avec l’API Bot Connector

Article
03/08/2023

Le service Bot Connector permet à votre bot d’échanger des messages avec des canaux configurés dans le Portail Azure, à l’aide de REST et JSON standard sur HTTPS. Ce didacticiel vous guide tout au long des processus d’obtention d’un jeton d’accès à partir de Bot Framework et d’utilisation du service Bot Connecteur pour échanger des messages avec l’utilisateur.

Obtention d’un jeton d’accès

Important

Si ce n’est déjà fait, vous devez inscrire votre bot auprès de Bot Framework pour obtenir son ID d’application et son mot de passe. Vous aurez besoin de l’AppID et du mot de passe du bot pour obtenir un jeton d’accès.

Pour communiquer avec le service Bot Connector, vous devez indiquer un jeton d’accès dans l’en-tête Authorization de chaque requête API, au format suivant :

Authorization: Bearer ACCESS_TOKEN

Vous pouvez obtenir le jeton d’accès de votre bot en émettant une requête d’API.

Requête

Pour demander un jeton d’accès permettant d’authentifier les requêtes adressées au service Bot Connector, émettez la requête ci-après en remplaçant MICROSOFT-APP-ID et MICROSOFT-APP-PASSWORD par l’ID d’application et le mot de passe que vous avez obtenus lorsque vous avez inscrit votre bot auprès de 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

response

Si la demande réussit, vous recevrez une réponse HTTP 200 qui spécifie le jeton d’accès et des informations sur son expiration.

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

Conseil

Pour plus d’informations sur l’authentification dans le service Bot Connector, consultez l’article Authentification.

Échanger des messages avec l’utilisateur

Une conversation est une série de messages échangés entre un utilisateur et votre bot.

Recevoir un message de l’utilisateur

Lorsque l’utilisateur envoie un message, le service Bot Framework Connector publie une requête destinée au point de terminaison que vous avez spécifié lorsque vous avez inscrit votre bot. Le corps de la requête est un objet Activité. L’exemple ci-après présente le corps de la requête qu’un bot reçoit lorsque l’utilisateur lui envoie un message simple.

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

Répondre au message de l’utilisateur

Lorsque le point de terminaison de votre bot reçoit une POST requête qui représente un message de l’utilisateur (par exemple, type = un message), utilisez les informations contenues dans cette demande pour créer l’objet Activity pour votre réponse.

Définissez la propriété conversation sur le contenu de la propriété conversation dans le message de l’utilisateur.
Définissez la propriété from sur le contenu de la propriété recipient dans le message de l’utilisateur.
Définissez la propriété recipient sur le contenu de la propriété from dans le message de l’utilisateur.
Définissez les propriétés text et attachments selon vos besoins.

Utilisez la propriété serviceUrl dans la requête entrante pour identifier l’URI de base que votre bot doit utiliser pour émettre sa réponse.

Pour envoyer la réponse, utilisez la requête POST pour publier votre objet Activity sur /v3/conversations/{conversationId}/activities/{activityId}, comme indiqué dans l’exemple suivant. Le corps de cette requête est un objet Activity qui invite l’utilisateur à sélectionner une heure de rendez-vous disponible. Pour plus d’informations sur la définition de l’URI de base, voir Informations de référence sur l’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..."
}

Dans cet exemple de demande, https://smba.trafficmanager.net/teams représente l’URI de base. L’URI de base pour les demandes émises par votre robot peut être différente. Pour plus d’informations sur la définition de l’URI de base, voir Informations de référence sur l’API.

Important

Comme indiqué dans cet exemple, l’en-tête Authorization de chaque requête d’API que vous envoyez doit contenir le mot Bearer suivi du jeton d’accès que vous avez obtenu auprès de Bot Framework.

Pour envoyer un autre message permettant à un utilisateur de sélectionner une heure de rendez-vous disponible en cliquant sur un bouton, utilisez la requête POST pour publier une autre requête destinée au même point de terminaison :

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

Étapes suivantes

Ce didacticiel vous a appris à obtenir un jeton d’accès à partir de Bot Framework et à utiliser le service Bot Connecteur pour échanger des messages avec l’utilisateur. Vous pouvez utiliser l’application Bot Framework Emulator pour tester et déboguer votre bot. Si vous souhaitez partager votre bot avec d’autres, vous devrez le configurer pour qu’il s’exécute sur un ou plusieurs canaux.