Using the Chatbot CLI

The Zoom Node.js Chatbot Command Line Interface accelerates the Zoom Chatbot development process.

To get started follow the instructions below, or checkout the sample app.

Prerequisites

A way to expose your localhost server so your Chatbot can be installed and tested on the Zoom Client. In this tutorial, I’ve used Ngrok.

Installation

To get started install the @zoomus/chatbot-cli NPM package.

$ npm install @zoomus/chatbot-cli -g

Setup

In this tutorial we are going to make a Zoom Chatbot that sends random cat pictures.

Run the following command in terminal to create a new Chatbot project called catbot:

$ zoomchatbot create catbot

You will be prompted to choose form 4 options:

Option	Description
general	Server deployment without a database. (Think Heroku or AWS EC2).
serverless	Serverless deployment without a database. (Think AWS Lambda).
general-demo-withdynamodb	Server deployment with a database. (Think Heroku or AWS EC2 with Dynamo / Mongo or SQL / Postgres). Database for storing 3rd party API / OAuth2 tokens / user data.
serverless-demo-withdynamodb	Serverless deployment with a database. (Think AWS Lambda with Dynamo / Mongo or SQL / Postgres). Database for storing 3rd party API / OAuth2 tokens / user data.

Choose any of these options for the tutorial.

This will create a directory named catbot and generate the Chatbot code inside it.
cd into the catbot folder:

$ cd catbot
Start your Ngrok server so your Chatbot can be installed and tested on the Zoom Client:

$ ngrok http 3000

NOTE: I’ve put ngrok in my PATH so I can call it globally.
Copy the Ngrok https URL displayed in terminal. This url needs to be added to our Chatbots App Dashboard in Zoom. Keep the server running and the tab open.
If you haven’t already, head over to https://marketplace.zoom.us/develop/create and create a Chatbot named catbot.

Add the following URLs to your Chatbot app in the Zoom App Marketplace:

Input	Description	Example Value
Development Redirect URL for OAuth	It can be found in marketplace under App Credentials.	https://{{subdomain}}.ngrok.io/auth
Whitelist URL	It can be found in marketplace under App Credentials.	https://{{subdomain}}.ngrok.io
Deauth Endpoint URL	It can be found in marketplace under Information.	https://{{subdomain}}.ngrok.io/deauth
Development and Production Bot Endpoint URL	It can be found in marketplace under Features.	https://{{subdomain}}.ngrok.io/command
Slash Command	How you address your Chatbot. Currently slash commands need to be globally unique, so you won’t be able to use the word `catbot`. It can be found in marketplace under Features.	catbot123

NOTE: Make sure to click “Save” after entering the Development and Production Bot Endpoint URL and the Slash Command.

Here are screenshots of each page and required input,

App Credentials page, Redirect URL for OAuth input:

Zoom Chatbot Redirect URL

App Credentials page, Whitelist URL input:

Zoom Chatbot Whitelist

Information page, Deauthorization Notification Endpoint URL input:

Zoom Chatbot Deauth

Features page, Usage Hint input:

Zoom Chatbot Usage Hint

Features page, Command input, Bot endpoint URL[development] input, Bot endpoint URL[production] input.

Zoom Chatbot Features

Make sure to click “Save”.

On the “Scopes” page, choose the imchat:bot scope.

To connect your Chatbot credentials to your code, open your project in a text editor. Follow the steps for the Chatbot install option you chose:

general or general-demo-withdynamodb
serverless or serverless-demo-withdynamodb

general or general-demo-withdynamodb

Open the .development.env file and fill in the following values (make sure to add the catApiKey key):

Key	Description	Example Value
`zoomClientId`	Development Client ID of your Chatbot. It can be found in marketplace under App Credentials.	`UD20wEqgQMyNmiR5IhinXA`
`zoomClientSecret`	Development Client Secret of your Chatbot. It can be found in marketplace under App Credentials.	`zlqppuDRGzQzW9j2eBpbUmyREPSbuTSU`
`zoomVerifyCode`	Verification Token of your Chatbot. It can be found in marketplace under Features.	`uaJs0IZvTIC0aP_Vs6d6IQ`
`zoomBotJid`	Development Bot JID of your Chatbot. It can be found in marketplace under Features.	`v1wjk1u1acrraq_mhwf2gclg@xmpp.zoom.us`
`zoomRedirect_uri`	Your ngrok URL with the `auth` path appended to the end.	`https://{{subdomain}}.ngrok.io/auth`
`catApiKey`	Get your Cat API Key here.	`71c45d-530d-4280-96f8-6ec16f2315`

Save and close the .development.env file.

serverless or serverless-demo-withdynamodb

Open the serverless.development.json file and fill in the following values in the environment object (make sure to add the "catApiKey" key):

Key	Description	Example Value
`"zoomClientId"`	Development Client ID of your Chatbot. It can be found in marketplace under App Credentials.	`UD20wEqgQMyNmiR5IhinXA`
`"zoomClientSecret"`	Development Client Secret of your Chatbot. It can be found in marketplace under App Credentials.	`zlqppuDRGzQzW9j2eBpbUmyREPSbuTSU`
`"zoomRedirect_uri"`	Your ngrok URL with the `auth` path appended to the end.	`https://{{subdomain}}.ngrok.io/auth`
`"zoomVerifyCode"`	Verification Token of your Chatbot. It can be found in marketplace under Features.	`uaJs0IZvTIC0aP_Vs6d6IQ`
`"zoomBotJid"`	Development Bot JID of your Chatbot. It can be found in marketplace under Features.	`v1wjk1u1acrraq_mhwf2gclg@xmpp.zoom.us`
`"catApiKey"`	Get your Cat API Key here.	`71c45d-530d-4280-96f8-6ec16f2315`

Save and close the serverless.development.json file.

Start your Chatbot by running the following command in a new terminal tab:

$ npm run start
If you chose general-demo-withdynamodb or serverless-demo-withdynamodb start your database by running:

$ npm run dynamodb

Adding Custom Slash Commands

To add custom slash commands to your Chatbot, open the botConfig.js file.

The botConfig.js file is where the configuration and customization lives for your Chatbot.

Open a new terminal tab and create a file new file named catPicture.js inside the src directory:

$ touch catPicture.js

Add the following code to the catPicture.js file you just created:

let request = require('request');
module.exports = async (req, res) => {

  let { zoomApp, zoomError, zoomWebhook, databaseModels } = res.locals;
  let { type, payload } = zoomWebhook;
  let { toJid, accountId, actionItem, userId } = payload;

  // get a cat photo from the cat api
  request({
    url: 'https://api.thecatapi.com/v1/images/search?mime_types=jpg,png',
    method: 'GET',
    headers: {
      'x-api-key': process.env.catApiKey
    }
  }, async function(error, response, body) {
    if (error) {
      // handle error
    } else {
      // cat api image response payload
      body = JSON.parse(body)
      // send Chatbot message to Zoom Chat by passing in a message object
      await zoomApp.sendMessage({
        to_jid: zoomWebhook.payload.toJid,
        account_id: zoomWebhook.payload.accountId,
        user_jid: zoomWebhook.payload.userJid,
        content: {
          header: {
            text: 'Cat Picture'
          },
          body: [{
            type: 'section',
            sections: [{
              type: 'attachments',
              img_url: body[0].url,
              resource_url: body[0].url,
              information: {
                title: {
                  text: 'Meow'
                },
                description: {
                  text: 'Click to download me'
                }
              }
            },
            {
              type: 'actions',
              items: [
                {
                  text: 'Up Vote',
                  value: `1${body[0].id}`,
                  style: 'Primary'
                },
                {
                  text: 'Down Vote',
                  value: `0${body[0].id}`,
                  style: 'Danger'
                }
              ]
            }], // zoomWebhook is the slash command payload sent from zoom chat
            footer: `Sent by ${zoomWebhook.payload.userName}`
          }]
        }
      })
    }
  })
}

In the code above, we are passing a Chatbot Message Object with an Attachment and Buttons to the zoomApp.sendMessage() function which sends the Chatbot message to Zoom Chat.

In the botConfig.js file, add the following object to the botCommands array:

 {
   command: 'picture',
   callback: require('./src/catPicture.js')
 }

Save and close catPicture.js and botConfig.js.

Receiving User Actions

We can add UI Elements to Chatbot messages like buttons. Let’s add buttons to our Cat Picture message so we can up or down vote the random cat images we receive.

Create a file new file named catVote.js inside the src directory:

$ touch catVote.js

Add the following code to the catVote.js file you just created:

let request = require('request');
module.exports = async (req, res) => {

  let { zoomApp, zoomError, zoomWebhook, databaseModels } = res.locals;
  let { type, payload } = zoomWebhook;
  let { toJid, accountId, actionItem, userId } = payload;

  request({
    url: 'https://api.thecatapi.com/v1/votes',
    method: 'POST',
    headers: { // process.env.catApiKey is your cat api key stored in your database
      'x-api-key': process.env.catApiKey
    },
    json: { // payload.actionItem is the button action payload sent from zoom chat
      "image_id": payload.actionItem.value.substr(1),
      "value": parseInt(payload.actionItem.value[0])
    }
  }, async function(error, response, body) {
    if(error) {
      // handle error
    } else {
      // send Chatbot message to Zoom Chat by passing in a message object
      await zoomApp.sendMessage({
        to_jid: toJid,
        account_id: accountId,
        visible_to_user: userId,
        content: {
          body: [{
            type: 'message',
            text: `${payload.actionItem.text} received`
          }]
        }
      });
    }
  })
};

In the code above, we are passing a Chatbot Message Object with Text to the zoomApp.sendMessage() function which sends the Chatbot message to Zoom Chat.

In the botConfig.js file, replace the following object in the botActions array:

{
  command:'interactive_message_actions',
  callback:require('./src/interactive_message_actions.js')
}

with:

{
  command:'interactive_message_actions',
  callback:require('./src/catVote.js')
}

Save and close catVote.js and botConfig.js.

Installation and Authentication

To install and authenticate your Chatbot, go back to your Chatbot on the Zoom App Marketplace, navigate to the “Local Test” page, and click install.
Click “Authorize” to install your Chatbot.
You will then land on your redirect URL.
Now open Zoom Chat. You will notice that “catbot” appears on the right side under “APPS”.
Click on your “catbot” app, you will see the welcome message.

Using the Chatbot

Head to a channel, type /catbot picture, and hit enter.

You should see a photo of a Cat! :)
Try clicking the “Up Vote” button to up vote the cat picture.

You should see a chatbot message, only visible to you, of your vote!

Congratulations! You have created a Zoom Chatbot!

Deployment

To deploy, please edit .production.env for server or serverless.production.json for serverless with your production credentials. Server version can be deployed to Linux servers such as AWS EC2. Serverless can be deployed on serverless solutions such as AWS Lambda.

Sample App

Checkout the completed Catbot code here.

Zoom Chatbot Message Action