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.(You need to install zoom client 4.4 or up to use the actions function in the bot)

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/oauth2
• add webhook in marketplace feature > chat subscription > add command && add bot endpoint url,just like https://domain/webhook

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 
//errorHelp true is auto send hint message when your write in im is not match your configure commands
let zoomBot = client(clientId,verificationToken,botJid,botName)
.commands([{ command: 'create', description: 'create a new meeting', hint:' <userName> <date>'}])
.configurate({help:true,errorHelp:false})
.defaultAuth(oauth2Client.connect());

//webhook event and handle logic

//actions which include button,edit,dropdown,field_edit from zoom im

zoomBot.on('actions',async function(e){
  //action which include button|edit|dropdown|field_edit,info is a object which is {original:[Object],current:[Object]},see the API below for details
  let { payload, type, info, action } = e;
  let { toJid: to_jid, accountId: account_id, name } = payload;
  let connection=oauth2Client.connect();//create a auth connection which no need oauth2
  let app = zoomBot.create({auth: connection});
  //handle info logic
  try{
     await app.sendMessage({
        to_jid:payload.toJid,
        account_id:payload.accountId,
        body: {type:'message',text:'message'}, header: { text: 'title'}
      });
  }
  catch(e){
    //
  }
});

// slash which include commands in you chat
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: connection});
    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('/webhook', async function (req, res) {//get message api
  let { body, headers } = req;
  try{
   await zoomBot.handle({ body, headers }); 
   //data
  }
  catch(e){
    console.log(e);
  }
  res.send('ok');
});



//oauth2
oauth2Client.on('tokens', function (tokens){//when tokens create,update,this event will be trigger
  //store tokens in dynamodb
});
app.all('/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('/webhook', function (req, res) {//add webhook
  let { body, headers } = req;
  let info=zoomBot.parse({body,headers});
   if(info.status===true){
    //if event is notification,data format as follow,but if event is button|edit|field_edit|dropdown,the data format will be like {payload:Object,info:{original:Object,current:Object},action:'button|edit|field_edit|dropdown',event:'same as action',type:'one or group'},See the API below for details
    //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 Settings{
       default_sidebar_color:"string";// just like #778614 color value,to set message sidebar color
    }
    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;
        settings:Settings;//optional,main configure sidebar style
    }
*/

let backInfo = await userApp.sendMessage(option);

message event

handle request to use event

//err is object type,{type:'format|verify|triggerHelp|triggerNoMatchCommand',errorMessage}; if err===null,will hint no error
expressApp.get('/someapi', function(req, res, next) {
  let { body, headers } = req;
  try{
    await zoomBot.handle({ body, headers });
  }
  catch(e){
    console.log(e);
  }
  //also support as follow
  // 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,and event is notification,data format as follows
  {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 or field_edit
  }}
  if parse success,and event is edit|dropdown|button|field_edit,data format as follows
  {
    status:true,
    data:{
      payload:Object,
      info:{original:Object,current:Object},//see the info below for details
      action:'button|edit|dropdown|field_edit',
      event:'same as action',
      type:'one or group'
    }
  }

*/

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
/* 

  //in action event type

    Interface Event{
      type:string;//one or group which come from im user type
      payload:Payload;
      info:{original:Original,current:Current};//see the info below for details
      action:String;//button or dropdown or edit or field_edit
   }

   //in notification event type
   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('actions', function(event) {
  // handle your logic
});

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

action info format

button info

info:{
original:{"head":{"text":"reply from userName dev-lambda-bot-deploy"},"body":[{"type":"section","footer_icon":"https://platform.slack-edge.com/img/default_application_icon.png","footer":"some footer","sidebar_color":"#222222","sections":[{"type":"message","text":"section1"},{"type":"actions","limit":2,"items":[{"text":"button8888","style":"Danger","value":"button2"},{"text":"button3888","style":"Disabled","value":"button3"}]}]}]},
current:{"text":"button8888","value":"button2"}
}

dropdown info

info:{
original:{"head":{"text":"reply from userName dev-lambda-bot-deploy"},"body":[{"type":"select","text":"My Dropdown","style":{"color":"#987654","bold":false,"itatic":true},"selected_item":{"text":"t3","value":"v3"},"select_items":[{"text":"t1","value":"v1"},{"text":"t2","value":"v2"},{"text":"t3","value":"v3"},{"text":"t4","value":"v4"}]}]},
current:[{"value":"v4"}]
}

edit info

info:{
original:{"head":{"text":"reply from userName dev-lambda-bot-deploy"},"body":[{"type":"message","editable":true,"text":"sunday","style":{"color":"#000000"}}]},
current:{"origin":"sunday","target":"what's your name"}
}

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"
 }

//section message,can integration with button,footer,and so on,sidebar_color can't use in type message slack
{
        "type": "section",
        "footer_icon": "https://platform.slack-edge.com/img/default_application_icon.png",
        "footer": "some footer",
        "sidebar_color": "#222222",
        "sections": [
            {
                "type": "message",
                "text": "section1"
            },
            {
                "type": "actions",
                "limit": 3,
                "items": [
                    {
                        "text": "button8888",
                        "style": "Danger",
                        "value": "button2"
                    },
                    {
                        "text": "button3888",
                        "style": "Disabled",
                        "value": "button3"
                    },
                    {
                        "text": "button488",
                        "value": "button4"
                    }
                ]
            }
        ]
  }

//field message


{
              "type": "fields",
              "items": [
                  {
                      "key": "name",
                      "value": "lee yang",
                      "isName": true,
                      "short": true
                  },
                  {
                      "key": "zoom",
                      "value": "zoom.us",
                      "link": "https://zoom/us",
                      "short": true
                  }
              ]
   }

//attachment message

{
              "type": "attachments",
              "resource_url": "https://docs.google.com/document/d/test/edit?usp=drive_web",
              "img_url": "https://avatars1.githubusercontent.com/u/7495313?v=4",
              "size": 3000,
              "information": {
                  "title": {
                      "text": "test csv"
                  }
              }
 }


//edit message

{
            "type":"message",
            "editable": true,
            "text":"sunday",
            "style":{
                "color":"#000000"
            }
}

header type

{"text":"your header text"}
or
{"text":"your header text",
        "style":{
        "color":"#000000",
        "bold":true,
        "itatic":false
        }
}
// and you can also add sub head message

{"text":"your header text",
 "sub_head":{
        "text":"String",
        "style":{
            "color":"String",
            "bold":boolean,
            "itatic":boolean
        }
  }
}