Creación de un bot con el servicio Bot Connector con Bot Connector API

Artículo
10/07/2023

El servicio Bot Connector permite al bot intercambiar mensajes con canales configurados en el Azure Portal mediante REST estándar del sector y JSON a través de HTTPS. Este tutorial le guiará a través del proceso para obtener un token de acceso de Bot Framework y utilizar el servicio Bot Connector para intercambiar mensajes con el usuario.

Obtención de un token de acceso

Importante

Si aún no lo ha hecho, debe registrar el bot con Bot Framework para obtener su identificador de aplicación y contraseña. Necesitará el AppID y la contraseña del bot para obtener un token de acceso.

Para comunicarse con el servicio Bot Connector, debe especificar un token de acceso en el encabezado Authorization de cada solicitud de API, con este formato:

Authorization: Bearer ACCESS_TOKEN

Puede obtener el token de acceso para el bot si emite una solicitud de API.

Solicitud

Para solicitar un token de acceso que se pueda usar para autenticar las solicitudes al servicio Bot Connector, emita la siguiente solicitud, reemplace MICROSOFT-APP-ID y MICROSOFT-APP-PASSWORD con el identificador de aplicación y la contraseña que obtuvo cuando registró su 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

Response

Si la solicitud se realiza correctamente, recibirá una respuesta HTTP 200 que especifica el token de acceso y la información sobre su expiración.

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

Sugerencia

Para obtener más información sobre la autenticación en el servicio Bot Connector, consulte Autenticación.

Intercambiar mensajes con el usuario

Una conversación es una serie de mensajes que se intercambian un usuario y su bot.

Recibir un mensaje del usuario

Cuando el usuario envía un mensaje, Bot Framework Connector envía una solicitud al punto de conexión que se especificó cuando se registró el bot. El cuerpo de la solicitud es un objeto Actividad. En el siguiente ejemplo se muestra el cuerpo de la solicitud que recibe un bot cuando el usuario le envía un mensaje 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"
}

Responder al mensaje del usuario

Cuando el punto de conexión del bot recibe una POST solicitud que representa un mensaje del usuario (por ejemplo, type = mensaje), use la información de esa solicitud para crear el objeto Activity para la respuesta.

Establezca la propiedad conversation en el contenido de la propiedad conversation del mensaje del usuario.
Establezca la propiedad from en el contenido de la propiedad recipient del mensaje del usuario.
Establezca la propiedad recipient en el contenido de la propiedad from del mensaje del usuario.
Establezca las propiedades text y attachments según corresponda.

Use la propiedad serviceUrl de la solicitud entrante para identificar el URI base que el bot debería usar para emitir su respuesta.

Para enviar la respuesta, envíe mediante POST el objeto Activity a /v3/conversations/{conversationId}/activities/{activityId}, tal como se muestra en el siguiente ejemplo. El cuerpo de esta solicitud es un objeto Activity que solicita al usuario que seleccione una hora de cita disponible. Para obtener más información sobre cómo establecer el URI base, consulte API Reference (Referencia de la 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..."
}

En la solicitud del ejemplo, https://smba.trafficmanager.net/teams representa el URI base; el URI base para solicitudes que su bot emita puede ser distinto. Para obtener más información sobre cómo establecer el URI base, consulte API Reference (Referencia de la API).

Importante

Tal como se muestra en este ejemplo, el encabezado Authorization de cada solicitud de API que envíe debe contener la palabra Bearer (portador) seguida del token de acceso que obtuvo en Bot Framework.

Para enviar otro mensaje que permita al usuario seleccionar una hora de cita disponible al hacer clic en un botón, POST otra solicitud para el mismo punto de conexión:

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

Pasos siguientes

En este tutorial obtuvo un token de acceso de Bot Framework y usó el servicio Bot Connector para intercambiar mensajes con el usuario. Puede usar Bot Framework Emulator para probar y depurar el bot. Si desea compartir su bot con otros usuarios, deberá configurarlo para que se ejecute en uno o más canales.