Connect a bot to Webex Teams using the Webex adapter
APPLIES TO: SDK v4
In this article you will learn how to connect a bot to Webex using the adapter available in the SDK. This article will walk you through modifying the EchoBot sample to connect it to a Webex app.
Note
The instructions below cover the C# implementation of the Webex adapter. For instructions on using the JavaScript implementation, part of the BotKit libraries, see the BotKit Webex documentation.
Prerequisites
Access to a Webex team with sufficient permissions to login to create / manage applications at https://developer.webex.com/my-apps. If you do not have access to a Webex team you can create an account for free at www.webex.com.
Create a Webex bot app
Log into the Webex developer dashboard and then click the 'Create a new app' button.
On the next screen choose to create a Webex Bot by clicking 'Create a bot'.
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.

Click the 'Add bot' button.
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.

Wiring up the Webex adapter in your bot
Before you can complete the configuration of our Webex app, you need to wire up the Webex adapter into your bot.
Install the Webex adapter NuGet package
Add the Microsoft.Bot.Builder.Adapters.Webex NuGet package. For more information on using NuGet, see Install and manage packages in Visual Studio
Create a Webex adapter class
Create a new class that inherits from the WebexAdapter class. This class will act as our adapter for the Webex channel. 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");
};
}
}
Create a new controller for handling Webex requests
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. 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));
}
}
Inject Webex Adapter In Your Bot Startup.cs
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. The configuration settings, described in the next step, will be automatically used by the adapter.
services.AddSingleton<WebexAdapter, WebexAdapterWithErrorHandler>();
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 Bot Framework Authentication to be used with the Bot Adapter.
services.AddSingleton<BotFrameworkAuthentication, ConfigurationBotFrameworkAuthentication>();
// Create the default Bot Adapter (used for Azure Bot Service channels and emulator).
services.AddSingleton<IBotFrameworkHttpAdapter, BotFrameworkAdapterWithErrorHandler>();
// Create the default Bot Framework Adapter.
services.AddSingleton<WebexAdapter, WebexAdapterWithErrorHandler>();
Add Webex adapter settings to your bot's configuration file
- Add the 4 settings shown below to your appSettings.json file in your bot project.
{
"MicrosoftAppType": "",
"MicrosoftAppId": "",
"MicrosoftAppPassword": "",
"MicrosoftAppTenantId": "",
"WebexPublicAddress": "",
- Populate the WebexAccessToken setting within the Webex Bot Access Token, that was generated when creating your Webex bot app in the earlier steps. Leave the other 3 settings empty at this time, until we gather the information needed for them in later steps.
Complete configuration of your Webex app and bot
Create and update a Webex webhook
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. To do this your bot must be running, so that Webex can verify the URL to the endpoint is valid.
To complete this step, deploy your bot to Azure and make a note of the URL to your deployed bot. 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).Note
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.
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"Navigate to https://developer.webex.com/docs/api/v1/webhooks.
Click the link for the POST method
https://webexapis.com/v1/webhooks(with the description Create a webhook). This will display a form that allows you to send a request to the endpoint.
Populate the form with the following details:
- Name - The name for your webhook, for example Messages Webhook.
- TargetUrl - The full URL to your bot's Webex endpoint, such as
https://yourbotapp.azurewebsites.net/api/webex). - resource - Messages.
- event - Created.
- filter - Leave it blank.
- secret - A secret of your choice to secure your webhook. Later you will add it to your bot's
appsettings.json.

Click Run, which should create your webhook and provide you with a success message.
Complete the remaining settings in your bot application
Complete the remaining 3 settings in your bot's appsettings.json file (you already populated WebexAccessToken in an earlier step).
- WebexPublicAddress (the full URL to your bot's Webex endpoint)
- WebexSecret (the secret you provided when creating your webhook in the previous step)
- WebexWebhookName (the name for your webhook you provided in the previous step)
Re-deploy your bot in your Webex team
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 tunneling to a local endpoint using ngrok). Configuration of you Webex app and bot are now complete. 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.
