@zoomus/chatbot

Zoom Node.js Chatbot Library

The Zoom Node.js Chatbot Library wraps the OAuth2, sending messages, and receiving commands/actions functionality into easy to use functions you can import in your Node.js / Express app.

Installation

To get started install the @zoomus/chatbot NPM package to your existing Node.js Express app.

$ npm install @zoomus/chatbot --save

Setup

1. Import the @zoomus/chatbot into your app.
2. Add your Chatbot API credentials to the oauth2 and client functions.
3. Add a help command to let users know how to use your app.

const { oauth2, client } = require('@zoomus/chatbot')

const oauth2Client = oauth2('{{ CLIENT_ID }}', '{{ CLIENT_SECRET }}', '{{ REDIRECT_URL }}')

let chatbot = client('{{ CLIENT_ID }}', '{{ VERIFICATION_TOKEN }}', '{{ BOT_JID }}')
.commands([{ command: '/command', hint: 'this is a command you can type', description: 'This is what my chatbot does' }])
.configurate({ help: true, errorHelp: false })
.defaultAuth(oauth2Client.connect())

OAuth

After you install and authorize your app, you will be taken to your redirect url.

Add this code block to handle the redirect, grab the authorization code from the url, and to use the authorization code to request and save an access_token in memory.

app.get('/oauth2', function (req, res) {
  try {
    oauth2Client.connectByCode(req.query.code)
    res.send('Thanks for installing! Open Zoom to use this Chatbot!')
  } catch (error) { res.send(error) }
})

Authorization

The access_token is stored in memory when using the following auth flow. Each time you create an auth connection, it will check to see if your access_token is still valid. If it is expired or your server restarts and clears the access_token in memory, it will request a new one for you.

Here is the code for connecting to your oauth client and creating a chatbot constructor.

let connection = oauth2Client.connect()
let app = chatbot.create({ auth: connection })

Commands and Actions

To capture requests sent to our Bot endpoint URL, setup an express route that matches the path on our Bot endpoint URL.

Commands are slash commands a user types in Zoom Chat to interact with your Chatbot.

Actions are user interaction events with the Editable Text, Form Field, Dropdown, or Buttons message types in Zoom Chat.

Receiving Commands and Actions

This express post route will receive all Chatbot commands and actions, and handle them by passing the request data to the event handler. Based on if the event is a command or action, the respective event listener function will be called.

app.post('/webhook', async function (req, res) {
  let { body, headers } = req
  try {
    await chatbot.handle({ body, headers })
    res.send('ok')
  } catch (error) { console.log(error) }
})

Handling Commands

If the user types a slash command the chatbot.on('commands') function will be called, creating an auth instance and allowing you to write your apps logic. In this example we send a Chatbot message back to the user who sent the slash command.

chatbot.on('commands', async function (event) {
  let connection = oauth2Client.connect()
  let app = chatbot.create({ auth: connection })

  // write app logic here
})

Handling Actions

If the user interacts with the Editable Text, Form Field, Dropdown, or Buttons message types, the chatbot.on('actions') function will handle it. In this example we send a Chatbot message back to the user who sent the slash command.

chatbot.on('actions', async function (event) {
  let connection = oauth2Client.connect()
  let app = chatbot.create({ auth: connection })

  // write app logic here
})

Sending Messages

To send a Chatbot message, use the following code.

try {
  await app.sendMessage({
    to_jid: '{{ TO_JID }}',
    account_id: '{{ ACCOUNT_ID }}',
    header: { text: 'Chatbot' },
    body: { type: 'message', text: 'Hello World' }
  })
} catch (error) { console.log(error) }

You can customize the styling and message type by building a JSON message schema for the header and body objects.

Sample App

Check out our sample app built using this package that allows users to vote on topics in Zoom Chat.

Need Support?

The first place to look for help is on our Developer Forum, where Zoom Marketplace Developers can ask questions for public answers.

If you can’t find the answer in the Developer Forum or your request requires sensitive information to be relayed, please email us at [e-mail].