Wednesday, May 18, 2022
HomeHealthChatOps: Tips on how to Construct Your First Webex Bot

ChatOps: Tips on how to Construct Your First Webex Bot


Welcome to the primary weblog of our collection on how you can use the Webex API to code up ChatOps workflows! On this publish, you’ll discover ways 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 totally different facets of automation utilizing chat-driven interfaces.

Within the DevOps world, we’re all the time on the lookout for new methods to drive automation round communication. After we deploy new code, scale our deployments, or handle our characteristic flags – we wish our groups to learn about it. The Webex API makes it straightforward 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 the usage of chat shoppers like Webex Groups, chatbots, and real-time communication instruments to facilitate how software program growth 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 utility growth, safety ought to all the time be constructed into the preliminary steps of getting code up and working. Immediately, we’re going to maintain it easy and give attention to the fundamentals. Then, we’ll cowl how you can authenticate and authorize Webhook requests. We’ll maintain off on safety till the subsequent weblog publish in our ChatOps collection, 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.

Create a bot using the Webex Developer UI

Webex for Builders has a terrific step-by-step information right here that will help you rise up and working.

Some essential issues to contemplate:

  • Take into consideration what you wish to title your bot. It ought to be intuitive, however distinctive. Relying on the way you arrange your Webhook, it’s possible you’ll be typing the bot’s title quite a bit, so take that under consideration.
  • The key token that’s auto-generated to your bot is used for authenticating with the Webex API. If you use this token, Webex will deal with your bot like an actual person 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 just a few customers? The reply to that query could have an effect on the way you wish to title it, what icon you choose, and so on.

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

Use your bot access token to set up your webhook with Simple Webhook Listener

Tips on how to obtain Webhook Occasions domestically

Subsequent, you’ll must host your bot the place it may be accessed by Webex through API calls. If you happen to’re creating domestically 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 setting.

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

The ensuing output is the general public area title that you should use to tunnel via to an area port in your machine:

public domain name output used to tunnel through to a local port on laptop

Be aware: If you happen to’re having bother working localtunnel through the command line after putting in (as just a few individuals have reported right here), be sure your PATH contains the listing the place NPM installs your binaries. For instance, on a Mac, that’s /usr/native/bin. This command may 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 should use to register a Webex Webhook. Your Webex Webhook will take heed to particular occasions that happen throughout the Webex platform and notify your internet service through HTTP POST requests.

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

That is what my Postman request appears like:

Create Webhook Postman Request to build a Webex bot

Be happy 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: utility/json' 
--data-raw '{
    "title": "simple-webhook",
    "targetUrl": "https://tidy-falcon-64.loca.lt",
    "useful resource": "messages",
    "occasion": "created",
    "filter": "mentionedPeople=me"
}'

What’s essential to notice, is that Webex will ship notifications to the area that you simply specify in your POST request. If you happen to’re utilizing a tunnel into your native setting, checklist the area that was given to you if 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 barely notified when customers ship a message that particularly mentions it in a Webex Groups Room:

Building a Webex Bot Filter property for message notications

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 person making that request (on this case, our bot), and applies that id wherever it sees me referenced.

Alternatively, you’ll be able to set a filter that solely triggers notifications for direct messages to your bot, versus mentions in Webex rooms. Because the objective 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 incorporates an ID to your Webhook. Whereas you should use the Webex API to GET an inventory of your Webhooks, it may be a good suggestion to carry onto this, in case you wish to rapidly replace or delete this Webhook sooner or later.  The Postman assortment linked above shops essentially the most not too long ago created Webhook ID in an active_webhook setting variable robotically, which then powers the DELETE name in that assortment.

Postman creates Webhook ID to power DELETE call

Tips on how to create your bot server

For easy use instances, it’s possible you’ll wish to use the Webex Node Bot Framework, which is nice for fast implementation. With a purpose to get extra aware of the totally different parts concerned on this collection, we’ll begin from scratch, diving into the step that powers your Webex bot.

Getting Began with Categorical

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

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

Since my IDE handles JavaScript Modules quite a bit higher than it handles require statements, I opted to go along with a extra fashionable method for my dependency administration. That is completely non-compulsory 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 package deal.json file, anyplace within the root of the JSON object:

"kind": "module",

Loads of the boilerplate code might be stripped out if you happen to like – we received’t want a favicon, a public/ folder, or a customers route handler. Right here’s what my code appeared like after I stripped lots of the easy 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 you 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 the vast majority of the boilerplate. At this level, I solely have 4 recordsdata in my codebase, regardless of what number of Categorical offers me out of the field:

  • app.js
  • package deal.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 operate that prints the request physique to the appliance console – nothing sophisticated, just some traces of code:

// in routes/index.js

import specific from 'specific'

const router = specific.Router();

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

export default router;

Give it a attempt

You now have the entire essential parts for receiving message notifications from Webex:

  • A bot to behave as an id to your Webex interactions
  • If relevant, a community tunnel to show your native internet service to the general public web
  • A Webhook arrange by your bot to obtain Webex notifications
  • An internet 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 should 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 via to your working internet service, which ought to log the POST physique that it obtained in its console output:

running web service request for webex bot POST body console output

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

 What’s subsequent

As promised, our subsequent publish will stroll via the extraordinarily essential 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 that you would be able to automate on a regular basis workflows proper from a Webex Groups Room!

Study, practice, and certify in Cisco Collaboration

As you make your approach via this ChatOps collection, contemplate 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. Try 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 can provide help to solidify right this moment’s ChatOps give attention to constructing your first Webex bot.

Did you construct a Webex bot? I’d love to listen to the way it went. Depart me a remark under and let me know what you assume!

Comply with Cisco Studying & Certifications

Twitter, Fb, LinkedIn and Instagram.

Share:



RELATED ARTICLES

LEAVE A REPLY

Please enter your comment!
Please enter your name here

Most Popular

Recent Comments