risport-monitor-bot

This project implements a Botkit + Webex Teams adapter bot, based on the Cisco DevNet botkit-template, providing a sample bot which uses the Cisco Unified Communications Manager Risport API to monitor the registration status of phone devices.

See Risport

Websockets vs. Webhooks

Most Botkit features can be implemented by using the Webex Teams JS SDK websockets functionality, which establishes a persistent connection to the Webex Teams cloud for outbound and inbound messages/events.

Webex Teams also supports traditional HTTP webhooks for messages/events, which requires that your bot be accessible via a publically reachable URL. A public URL is also needed if your bot will be serving any web pages/files, e.g. images associated with the cards and buttons feature or the health check URL.

• If you don't need to serve buttons and cards images, you can set the environment variable WEBSOCKET_EVENTS=True and avoid the need for a public URL
• If you are implementing buttons & cards, you will need a public URL (e. g. by using a service like Ngrok, or hosting your bot in the cloud) - configure this via the PUBLIC_URL environment variable

How to run (local machine)

Assuming you plan to us ngrok to give your bot a publically available URL (optional, see above), you can run this template in a jiffy:

1. Clone this repo:

   git clone https://github.com/CiscoDevNet/risport-monitor-bot.git
   
   cd risport-monitor-bot

2. Install the Node.js dependencies:

   npm install

3. Create a Webex Teams bot account at 'Webex for Developers', and note/save your bot's access token

4. Launch Ngrok to expose port 3000 of your local machine to the internet:

   ngrok http 3000

   Note/save the 'Forwarding' HTTPS (not HTTP) address that ngrok generates

5. Rename the env.example file to .env, then edit to configure the settings and info for your bot.

   Note: you can also specify any of these settings via environment variables (which will take precedent over any settings configured in the .env file)...often preferred in production environments

   If running on Glitch.me or Heroku (with Dyno Metadata enbaled), the PUBLIC_URL will be auto-configured

   Additional values in the .env file (like OWNER and CODE) are used to populate the healthcheck URL meta-data.

6. In .env configure your CUCM address, and the Risport API user's username and password.

   Be sure to save the .env file!

7. If you wish to have a pre-populated list of devices to monitor (so you don't have to add them manually each time), see/edit features/risport.js

8. You're ready to run your bot:

   node bot.js

9. Add the bot to a multi-user or 1-on-1 space (be sure to @mention the bot in a multi-user space.)

   Add devices via risport add {devicename}

   Start monitoring via risport start

Quick start on Glitch.me

• Click

• Open the .env file, then uncomment the WEBEX_ACCESS_TOKEN variable and paste in your bot's access token

  Optional: enter appropirate info in the "Bot meta info..." section

  Note that thanks to Glitch PROJECT_DOMAIN env variable, you do not need to add a PUBLIC_URL variable pointing to your app domain

You bot is all set, responding in 1-1 and 'group' spaces, and sending a welcome message when added to a space!

You can verify the bot is up and running by browsing to its healthcheck URL (i.e. the app domain.)

Quick start on Heroku

• Create a new project pointing to this repo.

• Open your app settings, view your config variables, and add an WEBEX_ACCESS_TOKEN variable with your bot's access token as value.

• Unless your app is using Dyno Metadata, you also need to add a PUBLIC_URL variable pointing to your app domain.

You bot is all set, responding in 1-1 and 'group' spaces, and sending a welcome message when added to a space!

You can verify the bot is up and running by browsing to its healthcheck URL (i.e. the app domain.)