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

  1. 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.

  1. 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.
  2. Choose any of these options for the tutorial.

    This will create a directory named catbot and generate the Chatbot code inside it.

  3. cd into the catbot folder:

    $ cd catbot

  4. 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.

  5. 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.

    Zoom Chatbot Ngrok

  6. If you haven’t already, head over to https://marketplace.zoom.us/develop/create and create a Chatbot named catbot.

    Zoom Chatbot Marketplace

  7. 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”.

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

    Zoom Chatbot Scopes

  9. 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

    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.

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

    $ npm run start

  11. 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.

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

    $ touch catPicture.js

  2. 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.

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

     {
       command: 'picture',
       callback: require('./src/catPicture.js')
     }
    
  4. 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.

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

    $ touch catVote.js

  2. 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.

  3. 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')
    }
    
  4. Save and close catVote.js and botConfig.js.

Installation and Authentication

  1. 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.

    Zoom Chatbot Install

  2. Click “Authorize” to install your Chatbot.

    Zoom Chatbot Authorize

  3. You will then land on your redirect URL.

    Zoom Chatbot Redirect URL Page

  4. Now open Zoom Chat. You will notice that “catbot” appears on the right side under “APPS”.

    Zoom Chatbot Installed

  5. Click on your “catbot” app, you will see the welcome message.

    Zoom Chatbot Welcome Message

Using the Chatbot

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

    Zoom Client Chatbot Usage Hint

    You should see a photo of a Cat! :)

    Zoom Chatbot Message

  2. Try clicking the “Up Vote” button to up vote the cat picture.

    Zoom Chatbot Message Action

    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

Need help?

The first place to look is on our Developer Forum. If you can't find the answer or your request includes sensitive information, contact Developer Support.