zoom-bot-sdk

Zoom-bot-sdk

This library provide interfaces to quickly build bots and applications for Zoom Messaging framework. All the complexities of oAuth2, sending messages and receiving notifications to and from Zoom client are hidden within the library so that you can focus on building the business logic of your application.

Requirements

This package supports Node v8 and higher.

Installation

npm install zoom-bot-sdk

Features

Zoom connector offers Resource Owner && Authorization Server for you to integrate with zoom client . Each app can connect different user to trigger different actions.

Preparatory work

for developer，in marketplace

• click develop > build app > write app name&&select chat bot >create to create your new app
• add oauth url in marketplace App Credentials > redirect url for oauth ,just like https://domain/api/oauth2
• add webhook in marketplace feature > chat subscription > add command && add bot endpoint url,just like https://domain/api/message

Example

sendMessage

var express = require('express');
let app = express();
const { oauth2, client, setting } = require('zoom-bot-sdk');
//get clientId,clientSecret in marketplace  app credentials > copy your client id && client secret
let oauth2Client = oauth2(clientId,clientSecret,redirectUri);
//get verificationToken in marketplace feature > Verification Token 
let zoomBot = client(clientId,verificationToken,botJid,botName)
.commands([{ command: 'create', description: 'create a new meeting', hint:' <userName> <date>'}])
.defaultAuth(oauth2Client.connect());

//webhook event and handle logic,you can also use zoomBot.on('messages',async function(event){}) which include commands and random string from im,messages event||commands event only run one at a time,messages scope include commands,message has a higher priority is you bind it.

zoomBot.on('commands',async function(event){
    let {payload,data,type,command,message}=event;
    let connection=oauth2Client.connect();//create a auth connection which no need oauth2
    let app = zoomBot.create({auth: oauth2Client.connect()});
    try{
     await app.sendMessage({
        to_jid:payload.toJid,
        account_id:payload.accountId,
        body: {type:'message',text:'message'}, header: { text: 'title'}
      });
    }
    catch(e){console.log(e);}
});

//webhook bind
app.all('/api/message', function (req, res) {//get message api
  let { body, headers } = req;
  zoomBot.handle({ body, headers }, function (err) {
    if (err) { console.log(err); }
    res.send('ok');
  });
});



//oauth2
oauth2Client.on('tokens', function (tokens){//when tokens create,update,this event will be trigger
  //store tokens in dynamodb
});
app.all('/api/oauth2', function (req, res) {//get message api
 try { 
   let connection=await oauth2Client.connectByCode(req.query.code); //create a connection which include oauth2 tokens
   res.send('ok'); } 
   catch (e) { res.send(e); }
});

if you want to use api in zoom dev env

setting.setUrl('https://dev.zoom.us');

if you want to debug your app

setting.debug(true);

DEBUG=http node index.js //now we only support http debug

what is connection

connection is a auth instance , we can create connection by oauth2Client.connectByCode(code) , oauth2Client.connectByRefresh(refreshcode) , oauth2Client.connectByTokens(tokens) tokens is from your db store , oauth2Client.connect() if you only need sendmessage to zoom im and you have know the relevant account_id and to_jid (these two datas you can get from webhook event payload or getUser and channelList action)

after you create connection,you need bind it with your client instance ,just like let app=zoomBot.create({auth: oauth2Client.connect()}),the app instance which you can trigger the action

each user can create different connection,you can store some connections by own business demand

what is zoomBot

you can use zoomBot to configurate your commands,create account app, check command, parse webhook data and so on

zoomBot instance represents an bot on the marketplace , and after you use let app=zoomBot.create({auth: oauth2Client.connect()}) , you get a account instance which name app , you can use the account app to do the action ,just like get account id, sub user id , channel id in your current account , each app represents a new account.you can store you account app by own business demand

if you don't want to use event mode for bot webhook,you can use method as follows

app.all('/api/message', function (req, res) {//get message api
  let { body, headers } = req;
  let info=zoomBot.parse({body,headers});
   if(info.status===true){
    //comand:'create',hint:'<><>',message:'whole cmd string',type:'one or group',event:'notification'
    let {command,hint,payload,message,type,event}=info.data;
    let { toJid: to_jid, accountId: account_id } = payload;
    let app = zoomBot.create({auth: oauth2Client.connect()});
      //replay a message to zoom clinet
      try{
        await app.sendMessage({
          to_jid,
          account_id,
          body: {type:'message',''}, header: { text: ''}
        });
      }
      catch(e){
        //
      }
  }
  else{
    console.log(info.errorMessage);
  }
  res.send('msg');
});

this lib integrate help command

after you bind webhook , then you write help in zoom im, and lib will auto send default content(which you configure in commands([])) to im

and if you send message in im which is not config in commands,you can use zoomBot.configurate({errorHelp:true}) and will send help content after write the command which in commands config.

Usage

global

const { oauth2, client, setting } = require('zoom-bot-sdk');
// setting.setUrl('https://dev.zoom.us'); default is https://api.zoom.us . dev.zoom.us if for test

oauth2 with zoom

init oauth instance

// const {oauth2} =require('zoom-bot-sdk');
const oauth2Client=oauth2(Your Client Id,Your Client Secret,Your redirect url);

/*
interface ClientTokens{
access_token:string;
token_type:string;
refresh_token:string;
expire_in:number;
scope:string
}
*/
//trigger when get new tokens
oauth2Client.on("tokens",(tokens)=>{
//store tokens to db,or other handles
});

/*
interface ClientTokens{
access_token:string;
token_type:string;
refresh_token:string;
expire_in:number;
}
*/
//trigger when get new clientTokens
oauth2Client.on("clientTokens",(tokens)=>{

});

/*
interface Err{
    type:string;//temporary support value:(token|clientToken)
    message:any;
}
*/
oauth2Client.on("error",(err)=>{

});

create auth connection

//If you just have a sendmessage action requirement ， no need for get access_token,you can just use let connection= oauth2Client.connect();
//getUser and channelList need accessToken.
let connection = await oauth2Client.connectByCode(code);
let connection = await oauth2Client.connectByRefresh(refresh_token);
let connection = oauth2Client.connectByTokens(tokens);
// if you just need to trigger sendMessage action,and you already have account_id and group_jid from your db,you can just to use oauth2Client.connect(),and then you can use sendMessage action only
let connection = oauth2Client.connect(); //not auto request tokens

connection api

let tokens = await connection.requestTokensByRefresh(refresh_token);
let tokens = await connection.requestTokens(code);
let clientTokens = await connection.requestClientTokens();
let ifExpired = connection.expired(); //check access_token whether expired or not
let ifClientExpired = connection.expiredClient(); //check client access_token whether expired or not
let tokens = connection.getTokens();
let clientTokens = connection.getClientTokens();
connection.setTokens(tokens); //if you want to update tokens temporary

zoom client action && message

create zoombot instance and config command&&version for help command

// const {client}=require('zoom-bot-sdk');
//you can get verification token and robot_jid in zoom marketplace features.
/*
   Interface CommandObj{
      command:string;//your command name
      description:string;//your description of command
      hint?:string;//your command arguments
   }

   opts:CommandObj|Array<CommandObj>
*/
let zoomBot=client(your clientid,your Verification Token,your robot_jid)
.command(opts).defaultAuth(oauth2Client.connect());//you must to config a default auth for default help command,just use oauth2Client.connect()


//if you want to config help mode,help:true will auto send help content to zoom im after you input help in im,errorHelp:true will auto send help content to zoom im when you input in im which is not in your commands config.
zoomBot= zoomBot.configurate({help:true,errorHelp:true}); //default help:true,errorHelp:false


//you can check command to see whether it is in commands config , and then manual trigger help
let ifInCommands=zoombot.checkCommands(commandString);
if(!ifInCommands){await zoombot.triggerHelp(account_id,to_jid);}

create one business instance with oauth2 connection in zoombot

//if use auth argument no need to import tokens argument
//access_token will auto be requested when judge expired
const userApp = zoomBot.create({
  auth: connection
});

use business instance to handle action(for now,only support getUser,channelList,sendMessage three action,and you can also use request to request any api which not need to inject token auth)

use request to request any zoom open api

/* 

interface Option{
  url:string; //  /v2/groups or http://api.zoom.use...,
  path:string; //   /v2/groups
  method:string; //get ,post,delete..., default is get
  body:object;  // the data you want to send by post,application/json is most openapis zoom zpi used
  query:object; // url query
  form:object; //if you want to send data by x-www-form-urlencodeed
  formData:object;// if you want to send data by formdata
  timeout:number;
  header:object //will default integrate Authorization:.. for headers,you can overwrite it
}

type:string // can use access or credential,default is access which is access_token type
opt:Option

*/

await userApp.request(opt,type);

get user

//if email is empty ,will return userId corresponds to the current access_token ,if send specific email，will return the corresponding sub-account under account 。
/* 
   interface UserInfo{
       id:string;//user id
       account_id:string;
       email:string;
       [propName: string]: any;
   }
   email?:string
*/

let userInfo = await userApp.getUser(email);

get channelList


// the userId which you can get from getUser method or callback from on event message
/*
    interface ChannelItem{
       group_jid:string;
       name:string;
       type:number;
       created_time:number;
       modified_time:number;
    }

    channelInfo:Array<ChannelItem>
*/

let channelInfo=await userApp.channelList(userId);

sendMessage

/* 
    body example:
    {
      "type": "message",
      "text": "this is sendmessage info",
      "style": { "color": "#000000", "bold": true, "itatic": false }
    }

    header example:
    { "text": "kogss" }

    Body:Array<Msg>|Msg;

    Interface Header{
        text:String;
        style:Style;
    }
    Interface Option{
        account_id:String;//account_id from getUser action userInfo
        to_jid:String;//to_jid from channelList group_jid
        body:Body;// send one or multiple message
        header:Header;
    }
*/

let backInfo = await userApp.sendMessage(option);

message event

handle request to use event

expressApp.get('/someapi', function(req, res, next) {
  let { body, headers } = req;
  zoomBot.handle({ body, headers }, function(err) {
    if (err) {
      console.log(err);
    }
  });
  res.send('some res');
});

if don't use event

/* 

  info example
  if parse error
  {status:false,errorMessage:''}
  if parse success
  {status:true,data:{
    command:"create",
    hint:"<><>",
    message:"all cmd string",
    type:"one or group",
    payload:Payload,//View the definition of payload in the documentation
    event:notification or button or edit or dropdown
  }}

*/

expressApp.get('/someapi', function(req, res, next) {
  let { body, headers } = req;
  let info = zoomBot.parse({ body, headers });
  //use info to handle business
  res.send('some res');
});

listen message

now we only support notification message from im,We will support more message callbacks after the zoom client release, which won't be long

/* 
     interface Payload{
            robotJid:String;
            userJid:String;
            toJid:String,
            accountId:String,
            userId:String,
            name:String,
            timestamp:Number,
            cmd:String
        }
*/

//support multiple async function
//when have command : /zoom create foxjiang 2019-08-08
/* 
   Interface Event{
      type:string;//one or group which come from im user type
      payload:Payload;
      message:string;//origin content from im ,just like 'create foxjiang 2019-08-08'
      data:Array<string>;//just like ['foxjiang','2019-08-08']
      command:string;//notification,just like create
   }
*/

zoomBot.on('commands', function(event) {
  // handle your logic
});

zoomBot.on('messages',function(event){//different with commands,is messages can run when notification from im is command or other random string，which scope include commands, Message commands only runs one at a time,message has a higher priority is you bind it.
//handle your logic
});

body type

We will support more message body after the new zoom client release, which won't be long

//notification message
  {
            "type":"message",
            "text":"this is first message.",
            "style":{
               "color":"#FFFFFF",
               "bold":true,
               "itatic":false
            }
         }
//link message
 {
            "type":"message",
            "text":"zoom.us",
            "link":"https://zoom.us"
 }

header type

{"text":"your header text"}
or
{"text":"your header text",
        "style":{
        "color":"#000000",
        "bold":true,
        "itatic":false
        }
}

notice

old event app.command app.on('command',function(){}) was abandoned,but it still exists and is no longer maintained