webex.md

Botkit for Webex Teams Class Reference

← Botkit Documentation ← Class Index

This is a class reference for all the methods exposed by the botbuilder-adapter-webex package.

Classes

• WebexAdapter
• WebexBotWorker

Interfaces

• WebexAdapterOptions

---

WebexAdapter

Connect Botkit or BotBuilder to Webex Teams.

To use this class in your application, first install the package:

npm install --save botbuilder-adapter-webex

Then import this and other classes into your code:

const { WebexAdapter } = require('botbuilder-adapter-webex');

This class includes the following methods:

• continueConversation()
• deleteActivity()
• getIdentity()
• init()
• processActivity()
• registerAdaptiveCardWebhookSubscription()
• registerWebhookSubscription()
• resetWebhookSubscriptions()
• sendActivities()

Create a new WebexAdapter()

Parameters

Argument	Type	Description
config	WebexAdapterOptions

Create a Webex adapter. See WebexAdapterOptions for a full definition of the allowed parameters.

Use with Botkit:

const adapter = new WebexAdapter({
     access_token: process.env.ACCESS_TOKEN, // access token from https://developer.webex.com
     public_address: process.env.PUBLIC_ADDRESS,  // public url of this app https://myapp.com/
     secret: process.env.SECRET // webhook validation secret - you can define this yourself
});
const controller = new Botkit({
     adapter: adapter,
     // ... other configuration options
});

Use with BotBuilder:

const adapter = new WebexAdapter({
     access_token: process.env.ACCESS_TOKEN, // access token from https://developer.webex.com
     public_address: process.env.PUBLIC_ADDRESS,  // public url of this app https://myapp.com/
     secret: process.env.SECRET // webhook validation secret - you can define this yourself
});

// set up restify...
const server = restify.createServer();
server.use(restify.plugins.bodyParser());
// register the webhook subscription to start receiving messages - Botkit does this automatically!
adapter.registerWebhookSubscription('/api/messages');
// Load up the bot's identity, otherwise it won't know how to filter messages from itself
adapter.getIdentity();
// create an endpoint for receiving messages
server.post('/api/messages', (req, res) => {
     adapter.processActivity(req, res, async(context) => {
         // do your bot logic here!
     });
});

Properties and Accessors

Name	Type	Description
identity		Returns the identity of the bot, including {id, emails, displayName, created} and anything else from this spec

WebexAdapter Class Methods

continueConversation()

Standard BotBuilder adapter method for continuing an existing conversation based on a conversation reference. BotBuilder reference docs

Parameters

Argument	Type	description
reference	Partial<ConversationReference>	A conversation reference to be applied to future messages.
logic		A bot logic function that will perform continuing action in the form async(context) => { ... }

deleteActivity()

Standard BotBuilder adapter method to delete a previous message. BotBuilder reference docs.

Parameters

Argument	Type	description
context	TurnContext	A TurnContext representing the current incoming message and environment. (not used)
reference	Partial<ConversationReference>	An object in the form {activityId: <id of message to delete>, conversation: { id: <id of slack channel>}}

getIdentity()

Load the bot's identity via the Webex API. MUST be called by BotBuilder bots in order to filter messages sent by the bot.

init()

Botkit-only: Initialization function called automatically when used with Botkit. * Calls registerWebhookSubscription() during bootup. * Calls getIdentit() to load the bot's identity.

Parameters

Argument	Type	description
botkit	any

processActivity()

Accept an incoming webhook request and convert it into a TurnContext which can be processed by the bot's logic.

Parameters

Argument	Type	description
req	any	A request object from Restify or Express
res	any	A response object from Restify or Express
logic		A bot logic function in the form async(context) => { ... }

registerAdaptiveCardWebhookSubscription()

Register a webhook subscription with Webex Teams to start receiving message events.

Parameters

Argument	Type	description
webhook_path	any	the path of the webhook endpoint like /api/messages

registerWebhookSubscription()

Register a webhook subscription with Webex Teams to start receiving message events.

Parameters

Argument	Type	description
webhook_path	any	the path of the webhook endpoint like /api/messages

resetWebhookSubscriptions()

Clear out and reset all the webhook subscriptions currently associated with this application.

sendActivities()

Standard BotBuilder adapter method to send a message from the bot to the messaging API. BotBuilder reference docs.

Parameters

Argument	Type	description
context	TurnContext	A TurnContext representing the current incoming message and environment.
activities		An array of outgoing activities to be sent back to the messaging API.

WebexBotWorker

This is a specialized version of Botkit's core BotWorker class that includes additional methods for interacting with Webex Teams. It includes all functionality from the base class, as well as the extension methods below.

When using the WebexAdapter with Botkit, all bot objects passed to handler functions will include these extensions.

To use this class in your application, first install the package:

npm install --save botbuilder-adapter-webex

Then import this and other classes into your code:

const { WebexBotWorker } = require('botbuilder-adapter-webex');

This class includes the following methods:

• deleteMessage()
• replyInThread()
• startConversationInRoom()
• startConversationInThread()
• startPrivateConversation()

Properties and Accessors

Name	Type	Description
api	Webex	An instance of the webex api client

WebexBotWorker Class Methods

deleteMessage()

Delete an existing message.

Parameters

Argument	Type	description
update	Partial<BotkitMessage>	An object in the form of {id: <id of message to delete>}

// send a reply, capture the results
let sent = await bot.reply(message,'this is my original reply...');

// delete the sent message using the sent.id field
await bot.deleteMessage(sent);

replyInThread()

Like bot.reply, but as a threaded response to the incoming message rather than a new message in the main channel.

Parameters

Argument	Type	description
src	any	an incoming message object
resp	any	an outgoing message object (or part of one or just reply text)

startConversationInRoom()

Switch a bot's context into a different room. After calling this method, messages sent with bot.say and any dialogs started with bot.beginDialog will occur in this new context.

Parameters

Argument	Type	description
roomId	string	A Webex rooom id, like one found in message.channel
userId	string	A Webex user id, like one found in message.user

controller.hears('take this offline', 'message', async(bot, message) => {

     // switch to a different channel
     await bot.startConversationInRoom(WEBEX_ROOM_ID, message.user);

     // say hello
     await bot.say('Shall we discuss this matter over here?');
     // ... continue...
     await bot.beginDialog(ANOTHER_DIALOG);

});

Also useful when sending pro-active messages such as those sent on a schedule or in response to external events:

// Spawn a worker
let bot = await controller.spawn();

// Set the context for the bot's next action...
await bot.startConversationInRoom(CACHED_ROOM_ID, CACHED_USER_ID);

// Begin a dialog in the 1:1 context
await bot.beginDialog(ALERT_DIALOG);

startConversationInThread()

Switch a bot's context into a specific thread within a room. After calling this method, messages sent with bot.say and any dialogs started with bot.beginDialog will occur in this new context.

Parameters

Argument	Type	description
roomId	string	A Webex rooom id, like one found in message.channel
userId	string	A Webex user id, like one found in message.user
parentId	string	A webex message id that should be the parent message, like the one found in message.id

controller.hears('take this offline', 'message', async(bot, message) => {

     // switch to a different channel
     await bot.startConversationInThread(WEBEX_ROOM_ID, message.user, message.id);

     // say hello
     await bot.say('Shall we discuss this matter over here?');
     // ... continue...
     await bot.beginDialog(ANOTHER_DIALOG);

});

Also useful when sending pro-active messages such as those sent on a schedule or in response to external events:

// Spawn a worker
let bot = await controller.spawn();

// Set the context for the bot's next action...
await bot.startConversationInRoom(CACHED_ROOM_ID, CACHED_USER_ID);

// Begin a dialog in the 1:1 context
await bot.beginDialog(ALERT_DIALOG);

startPrivateConversation()

Change the context of the next message Due to a quirk in the Webex API, we can't know the address of the DM until after sending the first message. As a result, the internal tracking for this conversation can't be persisted properly. USE WITH CAUTION while we try to sort this out.

Parameters

Argument	Type	description
userId	string	user id of a webex teams user, like one from message.user

Interface WebexAdapterOptions

Fields

Name	Type	Description
access_token	string	An access token for the bot. Get one from https://developer.webex.com/
enable_incomplete	boolean	Allow the adapter to startup without a complete configuration. This is risky as it may result in a non-functioning or insecure adapter. This should only be used when getting started.
public_address	string	The root URL of your bot application. Something like https://mybot.com/
secret	string	Secret used to validate incoming webhooks - you can define this yourself
webhook_name	string	a name for the webhook subscription that will be created to tell Webex to send your bot webhooks.