ChatOps: Tips on how to Construct Your First Webex Bot

Welcome to the primary weblog of our sequence on learn how to use the Webex API to code up ChatOps workflows! On this publish, you’ll learn to create a Webex bot, register a Webhook in Webex, and configure your bot to take heed to Webhook – all with loads of code examples. Test again for extra as we construct new use instances that leverage completely different features of automation utilizing chat-driven interfaces.

Within the DevOps world, we’re at all times searching for new methods to drive automation round communication. Once we deploy new code, scale our deployments, or handle our function flags – we would like our groups to find out about it. The Webex API makes it simple to construct announcement flows triggered by profitable occasions in our infrastructure. Nonetheless, if we will set off these occasions from Webex as nicely, then we’ve entered the world of ChatOps.

ChatOps is using chat shoppers like Webex Groups, chatbots, and real-time communication instruments to facilitate how software program improvement and operation duties are communicated and executed. Utilizing Webex APIs, we will construct bots that enable us to enter instructions that handle our infrastructure, set off approval workflows, deploy code, and way more.

Safety Disclaimer

Safety is a prime concern right here at Cisco. In regular software improvement, safety ought to at all times be constructed into the preliminary steps of getting code up and working. At the moment, we’re going to maintain it easy and concentrate on the fundamentals. Then, we’ll cowl learn how to authenticate and authorize Webhook requests. We’ll maintain off on safety till the subsequent weblog publish in our ChatOps sequence, as soon as we’ve confirmed an end-to-end connection. 

Tips on how to create a Webex bot

First, let’s create a Webex bot utilizing the Webex Developer UI.

Webex for Builders has an important step-by-step information right here that can assist you rise up and working.

Some vital issues to contemplate:

• Take into consideration what you wish to title your bot. It must be intuitive, however distinctive. Relying on the way you arrange your Webhook, you might be typing the bot’s title lots, so take that into consideration.
• The key token that’s auto-generated on your bot is used for authenticating with the Webex API. If you use this token, Webex will deal with your bot like an actual consumer who can create messages, be part of rooms, or be tagged by different customers.
• Will this bot work together with lots of people? Will it have a really public presence, or will it solely talk with a number of customers? The reply to that query might have an effect on the way you wish to title it, what icon you choose, and many others.

When you’ve taken all of that into consideration and crammed out the bot creation type, it’s best to see one thing like this, which incorporates the all-important entry token:

Tips on how to obtain Webhook Occasions regionally

Subsequent, you’ll must host your bot the place it may be accessed by Webex through API calls. For those who’re creating regionally and wish to run a server that’s accessible to the web, the Webex information recommends localtunnel.me or ngrok.  I went with localtunnel.me for my native atmosphere.

$ npm i -g localtunnel
$ lt --port 3000

The ensuing output is the general public area title that you need to use to tunnel by to a neighborhood port in your machine:

Notice: For those who’re having bother working localtunnel through the command line after putting in (as a number of individuals have reported right here), make sure that your PATH consists of the listing the place NPM installs your binaries. For instance, on a Mac, that’s /usr/native/bin. This command would possibly assist:

$ npm config set prefix /usr/native
$ npm i -g localtunnel
$ lt --port 3000

Tips on how to register a Webhook

As soon as your internet-accessible endpoint has been arrange, you now have a site that you need to use to register a Webex Webhook. Your Webex Webhook will take heed to particular occasions that happen inside the Webex platform and notify your net service through HTTP POST requests.

There are a number of methods to register a webhook. Below the hood, nonetheless, all of them boil down to creating your individual HTTP POST request. I’ve posted a Postman assortment that you need to use to make this course of a bit of simpler. Fill in your individual atmosphere’s variables as you go and embrace the entry token used within the header.

That is what my Postman request seems to be like:

Be at liberty to make use of no matter know-how you want, together with good old-fashion CURL:

curl --location --request POST 'https://webexapis.com/v1/webhooks' 
--header 'Authorization: Bearer $BOT_TOKEN 
--header 'Content material-Sort: software/json' 
--data-raw '{
    "title": "simple-webhook",
    "targetUrl": "https://tidy-falcon-64.loca.lt",
    "useful resource": "messages",
    "occasion": "created",
    "filter": "mentionedPeople=me"
}'

What’s vital to notice, is that Webex will ship notifications to the area that you simply specify in your POST request. For those who’re utilizing a tunnel into your native atmosphere, checklist the area that was given to you whenever you activated your proxy.

A really impactful a part of your Webhook would be the filter property. This determines which Webex occasions are despatched to your bot as notifications (and that are filtered out). To maintain issues easy, my bot is just notified when customers ship a message that particularly mentions it in a Webex Groups Room:

Webex has a pleasant, handy tag for this: me makes use of the authorization token from the request to find out the id of the consumer making that request (on this case, our bot), and applies that id wherever it sees me referenced.

Alternatively, you possibly can set a filter that solely triggers notifications for direct messages to your bot, versus mentions in Webex rooms. For the reason that aim of this publish is to broaden visibility into the varied processes, these examples present interactions in a Webex Groups Room, nonetheless, each are equally viable choices.

If you ship your POST request, Webex will reply with a physique that accommodates an ID on your Webhook. Whereas you need to use the Webex API to GET an inventory of your Webhooks, it is likely to be a good suggestion to carry onto this, in case you wish to shortly replace or delete this Webhook sooner or later.  The Postman assortment linked above shops probably the most not too long ago created Webhook ID in an active_webhook atmosphere variable robotically, which then powers the DELETE name in that assortment.

Tips on how to create your bot server

For easy use instances, you might wish to use the Webex Node Bot Framework, which is nice for fast implementation. To be able to get extra conversant in the completely different parts concerned on this sequence, we’ll begin from scratch, diving into the step that powers your Webex bot.

Getting Began with Categorical

Let’s arrange an online server that may pay attention for POST requests from the Webex Webhook that we’ll create in a minute. This doesn’t should be sophisticated for now, simply one thing to exhibit that we’re capable of obtain requests. For simplicity, we will use the ExpressJS generator, however you need to use any net framework or know-how that you simply like.

$ npm i -g express-generator
$ cd the place/you/need/your/venture
$ specific

Since my IDE handles JavaScript Modules lots higher than it handles require statements, I opted to go together with a extra fashionable strategy for my dependency administration. That is completely optionally available and has no bearing on the way you arrange your code. Nonetheless, if you wish to comply with the code snippets as I’ve laid them out, you’ll wish to do the identical. Step one is so as to add the next key/worth pair to your bundle.json file, wherever within the root of the JSON object:

"kind": "module",

A whole lot of the boilerplate code will be stripped out should you like – we received’t want a favicon, a public/ folder, or a customers route handler. Right here’s what my code regarded like after I stripped numerous the straightforward stuff out:

// in app.js

// discover that I modified the require statements to make use of JS modules import statements
import specific from 'specific';
import logger from 'morgan';
import indexRouter from './routes/index.js';

const app = specific();
app.use(logger('dev'));
app.use(specific.json());
app.use(specific.urlencoded({ prolonged: false }));

app.use('/', indexRouter);

// boilerplate error code didn’t change
// …

// **make sure to keep in mind to set app because the default export on the finish of the file**
export default app;

Since I’m utilizing JS Modules, I additionally needed to change the executed file in an Categorical app www/bin to www/bin.js, and revise the boilerplate require statements there as nicely to make use of import syntax:

// in www/bin.js

/**
* Module dependencies.
*/

import app from '../app.js';
import _debugger from 'debug';
const debug = _debugger('chatops-webhook:server');
import http from 'http';

// nothing else on this file wanted to vary

Including a Route Handler

That takes care of nearly all of the boilerplate. At this level, I solely have 4 information in my codebase, regardless of what number of Categorical offers me out of the field:

• app.js
• bundle.json
• bin/www.js
• routes/index.js

We’ll wish to add a route handler that lets us know once we’ve obtained a POST request from our Webex Webhook. It may be a easy perform that prints the request physique to the appliance console – nothing sophisticated, only a few traces of code:

// in routes/index.js

import specific from 'specific'

const router = specific.Router();

router.publish('/', async perform(req, res) {
  console.log(`Acquired a POST`, req.physique);
  res.statusCode = 201;
  res.finish();
});

export default router;

Give it a attempt

You now have all the vital parts for receiving message notifications from Webex:

• A bot to behave as an id on your Webex interactions
• If relevant, a community tunnel to show your native net service to the general public web
• A Webhook arrange by your bot to obtain Webex notifications
• An online service to obtain Webex notifications on a POST endpoint

Let’s try it out!  To maintain issues easy for now, create a brand new room in Webex Groups and add your bot as a member. Subsequent, begin typing your message, mentioning your Bot (you need to use the @ image or kind its title) as a part of the textual content. If you hit enter, after a quick pause, it’s best to see a request come by to your working net service, which ought to log the POST physique that it obtained in its console output:

Congratulations, you’ve simply arrange your very personal Webex bot!

 What’s subsequent

As promised, our subsequent publish will stroll by the extraordinarily vital side of securing our bot. We’ll guarantee that solely Webex can entry it and solely licensed customers can set off automation. After that, we’ll transfer on to new and thrilling methods you can automate on a regular basis workflows proper from a Webex Groups Room!

Be taught, practice, and certify in Cisco Collaboration

As you make your means by this ChatOps sequence, think about validating your expertise with a Cisco Certification.

The 300-835 CLAUTO: Automating and Programming Cisco Collaboration Options is a 90-minute examination that counts towards three certifications — the CCNP Collaboration, Cisco Licensed DevNet Skilled, and Cisco Licensed DevNet Specialist – Collaboration Automation and Programmability certifications. Take a look at the CLAUTO examination subjects, and also you’ll discover that 25% of the examination covers Cloud Collaboration applied sciences. Earlier than we meet once more, take a while to flick thru the free CLAUTO Examine Supplies out there on the Cisco Studying Community, which is able to assist you to solidify right this moment’s ChatOps concentrate on constructing your first Webex bot.

Did you construct a Webex bot? I’d love to listen to the way it went. Go away me a remark beneath and let me know what you suppose!

Comply with Cisco Studying & Certifications

Twitter, Fb, LinkedIn and Instagram.

Share: