Conexión de un bot a equipos de Webex con el adaptador de WebexConnect a bot to Webex Teams using the Webex adapter

se aplica a: SDK V4APPLIES TO: SDK v4

En este artículo, aprenderá a conectar un bot a Webex mediante el adaptador disponible en el SDK.In this article you will learn how to connect a bot to Webex using the adapter available in the SDK. Este artículo le guiará en la modificación del ejemplo de bot de eco para conectarlo a una aplicación de WebEx.This article will walk you through modifying the EchoBot sample to connect it to a Webex app.

Nota

Las instrucciones siguientes tratan sobre la implementación en C# del adaptador de Webex.The instructions below cover the C# implementation of the Webex adapter. Para obtener instrucciones sobre el uso de la implementación de JavaScript, que forma parte de las bibliotecas de BotKit, consulte la documentación de BotKit sobre Webex.For instructions on using the JavaScript implementation, part of the BotKit libraries, see the BotKit Webex documentation.

PrerrequisitosPrerequisites

Creación de una aplicación de bot de WebExCreate a Webex bot app

  1. Inicie sesión en el panel del desarrollador de WebEx y, después, haga clic en el botón "Create a new app" (Crear una nueva aplicación).Log into the Webex developer dashboard and then click the 'Create a new app' button.

  2. En la siguiente pantalla, elija crear un bot de WebEx; para ello, haga clic en "Create a bot" (Crear un bot).On the next screen choose to create a Webex Bot by clicking 'Create a bot'.

  3. En la siguiente pantalla, escriba un nombre, un nombre de usuario y una descripción adecuados para el bot y elija un icono o cargue una imagen propia.On the next screen, enter an appropriate name, username and description for your bot, as well as choosing an icon or uploading an image of your own.

    configuración de bot

    Haga clic en el botón "Add bot" (Agregar bot).Click the 'Add bot' button.

  4. En la página siguiente, se le proporcionará un token de acceso para la nueva aplicación de WebEx; tome nota de este token, ya que lo necesitará al configurar el bot.On the next page you will be provided with an access token for your new Webex app, please make a note of this token as you will require it when configuring your bot.

    de la aplicación Twitter

Conexión del adaptador de Webex en el botWiring up the Webex adapter in your bot

Antes de poder completar la configuración de la aplicación de WebEx, debe conectar el adaptador de WebEx en el bot.Before you can complete the configuration of our Webex app, you need to wire up the Webex adapter into your bot.

Instalación del paquete de NuGet del adaptador de WebExInstall the Webex adapter NuGet package

Agregue el paquete de NuGet Microsoft.Bot.Builder.Adapters.Webex.Add the Microsoft.Bot.Builder.Adapters.Webex NuGet package. Para más información sobre el uso de NuGet, consulte Instalación y administración de paquetes en Visual Studio.For more information on using NuGet, see Install and manage packages in Visual Studio

Creación de una clase del adaptador de WebExCreate a Webex adapter class

Cree una nueva clase que herede de la clase *WebexAdapter _.Create a new class that inherits from the *WebexAdapter _ class. Esta clase actuará como nuestro adaptador para el canal de WebEx.This class will act as our adapter for the Webex channel. Incluye funciones de control de errores (muy parecido a la clase BotFrameworkAdapterWithErrorHandler que ya está en el ejemplo, que se usa para controlar las solicitudes de Azure bot Service).It includes error handling capabilities (much like the BotFrameworkAdapterWithErrorHandler class already in the sample, used for handling requests from Azure Bot Service).

public class WebexAdapterWithErrorHandler : WebexAdapter
{
    public WebexAdapterWithErrorHandler(IConfiguration configuration, ILogger<WebexAdapter> logger)
        : base(configuration, null, logger)
    {
        OnTurnError = async (turnContext, exception) =>
        {
            // Log any leaked exception from the application.
            logger.LogError(exception, $"[OnTurnError] unhandled error : {exception.Message}");

            // Send a message to the user
            await turnContext.SendActivityAsync("The bot encountered an error or bug.");
            await turnContext.SendActivityAsync("To continue to run this bot, please fix the bot source code.");

            // Send a trace activity, which will be displayed in the Bot Framework Emulator
            await turnContext.TraceActivityAsync("OnTurnError Trace", exception.Message, "https://www.botframework.com/schemas/error", "TurnError");
        };
    }
}

Creación de un nuevo controlador para controlar las solicitudes de WebExCreate a new controller for handling Webex requests

Creamos un nuevo controlador que controlará las solicitudes de la aplicación de Webex en un nuevo punto de conexión "api/webex" en lugar del punto de conexión "api/messages" predeterminado que se usa para las solicitudes de los canales de Azure Bot Service.We create a new controller which will handle requests from your Webex app, on a new endpoint 'api/webex' instead of the default 'api/messages' used for requests from Azure Bot Service Channels. Al agregar un punto de conexión adicional al bot, puede aceptar solicitudes de canales de Bot Service (o adaptadores adicionales), así como de WebEx, con el mismo bot.By adding an additional endpoint to your bot, you can accept requests from Bot Service channels (or additional adapters), as well as from Webex, using the same bot.

[Route("api/webex")]
[ApiController]
public class WebexController : ControllerBase
{
    private readonly WebexAdapter _adapter;
    private readonly IBot _bot;

    public WebexController(WebexAdapter adapter, IBot bot)
    {
        _adapter = adapter;
        _bot = bot;
    }

    [HttpPost]
    public async Task PostAsync()
    {
        // Delegate the processing of the HTTP POST to the adapter.
        // The adapter will invoke the bot.
        await _adapter.ProcessAsync(Request, Response, _bot, default(CancellationToken));
    }
}

Inserción del adaptador de Webex en el archivo Startup.cs del botInject Webex Adapter In Your Bot Startup.cs

Agregue la siguiente línea al método ConfigureServices en el archivo startup.CS, que registrará el adaptador WebEx y lo pondrá a disposición de la nueva clase de controlador.Add the following line into the ConfigureServices method within your Startup.cs file, which will register your Webex adapter and make it available for your new controller class. El adaptador usará automáticamente la configuración, que se describe en el paso siguiente.The configuration settings, described in the next step, will be automatically used by the adapter.

services.AddSingleton<WebexAdapter, WebexAdapterWithErrorHandler>();

Una vez agregado, el método ConfigureServices debe tener el siguiente aspecto.Once added, your ConfigureServices method should look like this.

// This method gets called by the runtime. Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    services.AddHttpClient().AddControllers().AddNewtonsoftJson();

    // Create the default Bot Framework Adapter.
    services.AddSingleton<IBotFrameworkHttpAdapter, BotFrameworkAdapterWithErrorHandler>();

    // Create the default Bot Framework Adapter.
    services.AddSingleton<WebexAdapter, WebexAdapterWithErrorHandler>();

    // Create the bot as a transient. In this case the ASP Controller is expecting an IBot.
    services.AddTransient<IBot, EchoBot>();
}

Adición de la configuración del adaptador de WebEx al archivo de configuración del botAdd Webex adapter settings to your bot's configuration file

  1. Agregue las 4 opciones de configuración que se muestran a continuación al archivo appSettings.json en el proyecto del bot.Add the 4 settings shown below to your appSettings.json file in your bot project.
{
  "WebexPublicAddress": "",
  "WebexAccessToken": "",
  "WebexSecret": "",
  "WebexWebhookName": ""
}
  1. Rellene el valor _ WebexAccessToken* en el token de acceso WebEx bot que se generó al crear la aplicación de bot de WebEx en los pasos anteriores.Populate the _ WebexAccessToken* setting within the Webex Bot Access Token, that was generated when creating your Webex bot app in the earlier steps. Deje los otros 3 valores de configuración vacíos en este momento, hasta que recopilemos la información necesaria para ellos en pasos posteriores.Leave the other 3 settings empty at this time, until we gather the information needed for them in later steps.

Configuración completa de la aplicación y el bot de WebExComplete configuration of your Webex app and bot

Creación y actualización de un webhook de WebExCreate and update a Webex webhook

Ahora que ha creado una aplicación de WebEx y ha conectado el adaptador en el proyecto del bot, los pasos finales son configurar un webhook de WebEx, apuntarlo al punto de conexión correcto en el bot y suscribir la aplicación para asegurarse de que el bot recibe mensajes y datos adjuntos.Now that you have created a Webex app and wired up the adapter in your bot project, the final steps are to configure a Webex webhook, point it to the correct endpoint on your bot, and subscribe your app to ensure your bot receives messages and attachments. Para ello, el bot debe estar en ejecución, para que WebEx pueda comprobar que la dirección URL del punto de conexión es válida.To do this your bot must be running, so that Webex can verify the URL to the endpoint is valid.

  1. Para completar este paso, debe implementar el bot en Azure y anotar la dirección URL del bot implementado.To complete this step, deploy your bot to Azure and make a note of the URL to your deployed bot. El punto de conexión de mensajería de WebEx es la dirección URL del bot, que será la dirección URL de la aplicación implementada (o punto de conexión de ngrok), más "/api/webex" (por ejemplo, https://yourbotapp.azurewebsites.net/api/webex).Your Webex messaging endpoint is the URL for your bot, which will be the URL of your deployed application (or ngrok endpoint), plus '/api/webex' (for example, https://yourbotapp.azurewebsites.net/api/webex).

    Nota

    Si no está preparado para implementar el bot en Azure, o desea depurar el bot al usar el adaptador WebEx, puede usar una herramienta como ngrok (que probablemente ya tenga instalada si ha usado anteriormente el emulador de bot Framework) para Tunelizar hasta el bot que se ejecuta localmente y proporcionarle una dirección URL de acceso público para ello.If you are not ready to deploy your bot to Azure, or wish to debug your bot when using the Webex adapter, you can use a tool such as ngrok (which you will likely already have installed if you have used the Bot Framework Emulator previously) to tunnel through to your bot running locally and provide you with a publicly accessible URL for this.

    Si desea crear un túnel de ngrok y obtener una dirección URL al bot, use el siguiente comando en una ventana de terminal (se supone que el bot local se ejecuta en el puerto 3978, modifique los números de puerto en el comando si no es así).If you wish create an ngrok tunnel and obtain a URL to your bot, use the following command in a terminal window (this assumes your local bot is running on port 3978, alter the port numbers in the command if your bot is not).

    ngrok.exe http 3978 -host-header="localhost:3978"
    
  2. Vaya a https://developer.webex.com/docs/api/v1/webhooks.Navigate to https://developer.webex.com/docs/api/v1/webhooks.

  3. Haga clic en el vínculo del método post https://webexapis.com/v1/webhooks (con la descripción crear un webhook).Click the link for the POST method https://webexapis.com/v1/webhooks (with the description Create a webhook). Se mostrará un formulario que le permite enviar una solicitud al punto de conexión.This will display a form that allows you to send a request to the endpoint.

    punto de conexión de webhook

  4. Rellene el formulario con los detalles siguientes:Populate the form with the following details:

    1. Nombre : el nombre del webhook, por ejemplo mensajes webhook.Name - The name for your webhook, for example Messages Webhook.
    2. TargetUrl : la dirección URL completa del extremo WebEx de bot, como, por ejemplo, https://yourbotapp.azurewebsites.net/api/webex ).TargetUrl - The full URL to your bot's Webex endpoint, such as https://yourbotapp.azurewebsites.net/api/webex).
    3. Resource : mensajes.resource - Messages.
    4. creado por el evento .event - Created.
    5. filtro : déjelo en blanco.filter - Leave it blank.
    6. Secret : un secreto de su elección para proteger el webhook.secret - A secret of your choice to secure your webhook. Más adelante lo agregará a su bot appsettings.json .Later you will add it to your bot's appsettings.json.

    formulario de webhook

  5. Haga clic en Ejecutar. Se creará el webhook y se mostrará un mensaje de operación correcta.Click Run, which should create your webhook and provide you with a success message.

Finalización del resto de la configuración de la aplicación de botComplete the remaining settings in your bot application

Complete los 3 valores restantes en el archivo appsettings.json del bot (ya ha rellenado WebexAccessToken en un paso anterior).Complete the remaining 3 settings in your bot's appsettings.json file (you already populated WebexAccessToken in an earlier step).

  • WebexPublicAddress (dirección URL completa del punto de conexión de WebEx del bot)WebexPublicAddress (the full URL to your bot's Webex endpoint)
  • WebexSecret (secreto que proporcionó al crear el webhook en el paso anterior)WebexSecret (the secret you provided when creating your webhook in the previous step)
  • WebexWebhookName (nombre del webhook que proporcionó en el paso anterior)WebexWebhookName (the name for your webhook you provided in the previous step)

Reimplementación del bot en el equipo de WebexRe-deploy your bot in your Webex team

Ahora que ha completado la configuración del bot en appsettings.json, debe volver a implementar el bot (o reiniciar el bot si lo está tunelizando a un punto de conexión local mediante ngrok).Now that you have completed the configuration of your bot's settings in appsettings.json, you should re-deploy your bot (or restart your bot if you are tunnelling to a local endpoint using ngrok). Ahora se ha completado la configuración de la aplicación y el bot de Webex.Configuration of you Webex app and bot are now complete. Ahora puede iniciar sesión en el equipo de Webex en https://www.webex.com y conversar con el bot enviándole un mensaje, de la misma forma que se haría para contactar con otra persona.You can now login to your Webex team at https://www.webex.com and chat with your bot by sending it a message, in the same way you would contact another person.

persona de contacto