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
-
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:
App Credentials page, Whitelist URL input:
Information page, Deauthorization Notification Endpoint URL input:
Features page, Usage Hint input:
Features page, Command input, Bot endpoint URL[development] input, Bot endpoint URL[production] input.
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
Open the
.development.env
file and fill in the following values (make sure to add thecatApiKey
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 theenvironment
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
orserverless-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 thesrc
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 thebotCommands
array:{ command: 'picture', callback: require('./src/catPicture.js') }
-
Save and close
catPicture.js
andbotConfig.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 thesrc
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 thebotActions
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
andbotConfig.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.