Creación de un bot con el servicio de conector de bot con la API del conector de botCreate a bot with the Bot Connector service with the Bot Connector API

El servicio Bot Connector permite que su bot intercambie mensajes con los canales configurados en Azure Portal, mediante los estándares del sector JSON y REST a través de HTTPS.The Bot Connector service enables your bot to exchange messages with channels that are configured in the Azure Portal, by using industry-standard REST and JSON over 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.This tutorial walks you through the process of obtaining an access token from the Bot Framework and using the Bot Connector service to exchange messages with the user.

Obtener un token de accesoGet an access token

Importante

Si aún no lo ha hecho, deberá registrar el bot con Bot Framework para obtener su identificador de aplicación y la contraseña.If you have not already done so, you must register your bot with the Bot Framework to obtain its App ID and password. Necesitará el identificador de la aplicación del bot y la contraseña para obtener un token de acceso.You will need the bot's AppID and password to get an access token.

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:To communicate with the Bot Connector service, you must specify an access token in the Authorization header of each API request, using this format:

Authorization: Bearer ACCESS_TOKEN

Puede obtener el token de acceso para el bot si emite una solicitud de API.You can obtain the access token for your bot by issuing an API request.

SolicitudRequest

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.To request an access token that can be used to authenticate requests to the Bot Connector service, issue the following request, replacing MICROSOFT-APP-ID and MICROSOFT-APP-PASSWORD with the App ID and password that you obtained when you registered your bot with the 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

ResponseResponse

Si la solicitud se realiza correctamente, recibirá una respuesta HTTP 200 que especifica el token de acceso e información sobre la fecha de expiración.If the request succeeds, you will receive an HTTP 200 response that specifies the access token and information about its expiration.

{
    "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.For more details about authentication in the Bot Connector service, see Authentication.

Intercambiar mensajes con el usuarioExchange messages with the user

Una conversación es una serie de mensajes que se intercambian un usuario y su bot.A conversation is a series of messages exchanged between a user and your bot.

Recibir un mensaje del usuarioReceive a message from the user

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.When the user sends a message, the Bot Framework Connector POSTs a request to the endpoint that you specified when you registered your bot. El cuerpo de la solicitud es un objeto Actividad.The body of the request is an Activity object. En el siguiente ejemplo se muestra el cuerpo de la solicitud que recibe un bot cuando el usuario le envía un mensaje simple.The following example shows the request body that a bot receives when the user sends a simple message to the bot.

{
    "type": "message",
    "id": "bf3cc9a2f5de...",
    "timestamp": "2016-10-19T20:17:52.2891902Z",
    "serviceUrl": "https://smba.trafficmanager.net/apis",
    "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 usuarioReply to the user's message

Cuando el punto de conexión del bot recibe una solicitud POST que representa un mensaje del usuario (es decir, type = mensaje), use la información de esa solicitud para crear el objeto Actividad de la respuesta.When your bot's endpoint receives a POST request that represents a message from the user (i.e., type = message), use the information in that request to create the Activity object for your response.

  1. Establezca la propiedad conversation en el contenido de la propiedad conversation del mensaje del usuario.Set the conversation property to the contents of the conversation property in the user's message.
  2. Establezca la propiedad from en el contenido de la propiedad recipient del mensaje del usuario.Set the from property to the contents of the recipient property in the user's message.
  3. Establezca la propiedad recipient en el contenido de la propiedad from del mensaje del usuario.Set the recipient property to the contents of the from property in the user's message.
  4. Establezca las propiedades text y attachments según corresponda.Set the text and attachments properties as appropriate.

Use la propiedad serviceUrl de la solicitud entrante para identificar el URI base que el bot debería usar para emitir su respuesta.Use the serviceUrl property in the incoming request to identify the base URI that your bot should use to issue its response.

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.To send the response, POST your Activity object to /v3/conversations/{conversationId}/activities/{activityId}, as shown in the following example. El cuerpo de esta solicitud es un objeto Activity que solicita al usuario que seleccione una hora de cita disponible.The body of this request is an Activity object that prompts the user to select an available appointment time.

POST https://smba.trafficmanager.net/apis/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/apis representa el URI base; el URI base para solicitudes que su bot emita puede ser distinto.In this example request, https://smba.trafficmanager.net/apis represents the base URI; the base URI for requests that your bot issues may be different. Para obtener más información sobre cómo establecer el URI base, consulte API Reference (Referencia de la API).For details about setting the base URI, see API Reference.

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.As shown in this example, the Authorization header of each API request that you send must contain the word Bearer followed by the access token that you obtained from the 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:To send another message that enables a user to select an available appointment time by clicking a button, POST another request to the same endpoint:

POST https://smba.trafficmanager.net/apis/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 siguientesNext steps

En este tutorial obtuvo un token de acceso de Bot Framework y usó el servicio Bot Connector para intercambiar mensajes con el usuario.In this tutorial, you obtained an access token from the Bot Framework and used the Bot Connector service to exchange messages with the user. Puede usar Bot Framework Emulator para probar y depurar el bot.You can use the Bot Framework Emulator to test and debug your bot. Si desea compartir su bot con otros usuarios, deberá configurarlo para que se ejecute en uno o más canales.If you'd like to share your bot with others, you'll need to configure it to run on one or more channels.