Getting started with using Zoom APIs
Hello and Namaste !
This is a story on how we can use Zoom APIs in our application so that we can schedule Zoom meetings from our application and more.
This is important to know that Zoom APIs are secured by OAuth 2.0.
Following OAuth 2.0 protocols, here are few of the steps we will have to do to use Zoom APIs:
- Get Authorization Code
- Use Authorization Code to issue Access Token
- Use Access Token to make Zoom API calls
- Use Refresh Token
Get Authorization Code
In order to get the Authorization Code, there are few steps here as well.
- We have to authenticate the User; User has Zoom Account.
- If only user is authenticated, we have to ask consent from the User so that our application can use their information and make Zoom API calls.
- If only yes, we get the Authorization Code.
These for the most part are all handled by Zoom OAuth App.
So, we first have to create Zoom OAuth app.
Creating and configuring Zoom OAuth App
Visit https://marketplace.zoom.us/develop/create.
Make sure you have access right for creating OAuth app if your account is managed by organization.
Click on Create.
Fill in the App Name.
There are two app types here.
Choose the app type according to your application business model.
For this story, we will create User-managed app. This will allow individual to integrate their accounts and manage, schedule Zoom meetings via our application.
Publishing to Zoom Marketplace will make the Zoom OAuth app public. External users will be able see and install our app.
Zoom marketplace: https://marketplace.zoom.us/
We can leave this toggle as off. We can always publish our app when needed.
Also, note that publishing this app to the Zoom marketplace is a long process.
In order to publish the app, we will have to fill in all the information requested in the form below, wait for approval from Zoom and few more days to be seen by public in Zoom marketplace.
We will fill in information just enough to make it work.
In App credentials, we will fill in the Redirect URL for OAuth and add this url to allow lists as well. This URL is used by Zoom to redirect user to this URL when authentication is successful.
Keep note of ClientId and ClientSecret here. They are used to get Access Token from Authorization Code.
For this story, We will just use in something like: http://localhost:3000/zoom
In Information, we will fill in short description, long description, developer contact name and developer contact email.
Next step is to add Scopes.
Scopes define the API methods this app is allowed to call, and thus which information and capabilities are available on Zoom. Scopes are restricted to specific resources like channels or files. If your app is submitted to Zoom, we will review your request for each scope. After your app is live, it will only be able to use permission scopes that Zoom approved.
Source: Zoom
We will just add two scopes to view and manage Zoom meetings.
Go to Activation to find the install link.
Back to getting Authorization Code
When we open this link (either by clicking install or copying), since the app is not published, other zoom accounts beside our account cannot install this app.
Once authorized, we will be redirected to URL mentioned above with Authorization Code.
Eg.: http://localhost:3000/zoom?code=authorization_code
Here, we get our Authorization Code.
Use Authorization Code to issue Access Token
To issue Access Token, we make API call to Zoom’s Authorization Server.
Below is API request detail:
API URL: https://api.zoom.us/oauth/token
Request Method: POST
Authorization Type: Basic
Here, username is ClientId and password is ClientSecret.
You can use Base64 encoded credential using ClientId and ClientSecret.
JavaString basicAuthEncoded =
Base64.getEncoder().encodeToString((clientId + ":" + clientSecret).getBytes());Node.jsvar basicAuthEncoded = Buffer.from(clientId + ':' + clientSecret).toString('base64');
Query Params:
grant_type: authorization_code
code: {Authorization Code}
redirect_uri: {Redirect URL from Zoom OAuth app}
Response:
{
"access_token": "...",
"token_type": "bearer",
"refresh_token": "...",
"expires_in": 3599,
"scope": "meeting:read meeting:write"
}Keep note of refresh token here. Refresh Token is used to issue new access token when access token expires.
Use Access Token to make Zoom API calls
Since, we only have scope to view and manage Zoom meetings, we can limited to APIs from here.
Example of using API to create and list Zoom meetings:
Creating a Zoom meeting
We will use POST /users/{userId}/meetings API.
Here, we pass me as {userId}. This will create meeting in Zoom account of access token holder.
There are lots of information to be passed in Request Body for this. We will only schedule instant meeting here with only few information.
API URL: https://api.zoom.us/v2/users/me/meetings
Request Method: POST
Authorization Type: Bearer Token
HeaderAuthorization: Bearer {access_token}
Content-Type: application/json
Request Body:
{
"topic": "Medium Test Meeting",
"type": 2, //2 - Scheduled Meeting
"start_time": "2022-01-21T09:20:00", //yyy-MM-dd'T'HH:mm:ss
"duration": 30,
"timezone": "UTC",
"password": "password12",
"agenda": "Test Agenda",
"settings": {
"host_video": false,
"participant_video": false,
"cn_meeting": false,
"in_meeting": false,
"join_before_host": false,
"mute_upon_entry": true,
"watermark": false,
"use_pmi": false,
"approval_type": 2, //2 - No Registration Required
"audio": "both", //both - Telephony and VoIP
"auto_recording": "cloud" //cloud - record on cloud
}
}For more information on predefined values, go through schema in https://marketplace.zoom.us/docs/api-reference/zoom-api/meetings/meetingcreate.
For timezone, visit: https://marketplace.zoom.us/docs/api-reference/other-references/abbreviation-lists#timezones
Response Body:
{
"uuid": "/VjWTwEkR+6qHMwr7FAsSw==",
"id": 78475495050,
"host_id": "...",
"host_email": "...",
"topic": "Medium Test Meeting",
"type": 2,
"status": "waiting",
"start_time": "2022-01-21T09:20:00Z"
"timezone": "UTC",
"agenda": "Test Agenda",
"created_at": "2022-01-21T09:08:12Z",
"start_url": "...",
"join_url": "...",
"password": "password12",
"h323_password": "5515440062",
"pstn_password": "5515440062",
"encrypted_password": "5SgV4MLgoKQ6DyIjMH2DuYKbcbAqsh.1",
"settings": {
"host_video": false,
"participant_video": false,
"cn_meeting": false,
"in_meeting": false,
"join_before_host": false,
"jbh_time": 0,
"mute_upon_entry": true,
"watermark": false,
"use_pmi": false,
"approval_type": 2,
"audio": "both",
"auto_recording": "none",
"enforce_login": false,
"enforce_login_domains": "",
"alternative_hosts": "",
"close_registration": false,
"show_share_button": false,
"allow_multiple_devices": false,
"registrants_confirmation_email": true,
"waiting_room": true,
"request_permission_to_unmute_participants": false,
"registrants_email_notification": true,
"meeting_authentication": false,
"encryption_type": "enhanced_encryption",
"approved_or_denied_countries_or_regions": {
"enable": false
},
"breakout_room": {
"enable": false
},
"alternative_hosts_email_notification": true,
"device_testing": false,
"focus_mode": false,
"private_meeting": false,
"email_notification": true
},
"pre_schedule": false
}We will use start_url if we want to start the meeting as a host and we share join_url with meeting participants.
Anyone can use start_url. This will temporarily give them access as host. So, we will have to be careful using it.
We will just have to open either of this two urls in our web browser. Zoom will handle the rest; either ask User to install Zoom app or open Zoom app for us.
List Zoom meetings
We will use GET /users/{userId}/meetings API.
Here, we pass me as {userId}. This will list all meetings scheduled in Zoom account of access token holder.
This API only supports scheduled meetings. This API does not return information about instant meetings.
API URL: https://api.zoom.us/v2/users/me/meetings
Request Method: GET
Authorization Type: Bearer Token
Response Body:
{
"page_size": 30,
"total_records": 1,
"next_page_token": "",
"meetings": [
{
"uuid": "/VjWTwEkR+6qHMwr7FAsSw==",
"id": 78475495050,
"host_id": "...",
"topic": "Medium Test Meeting",
"type": 2,
"start_time": "2022-01-21T09:20:00Z",
"duration": 30,
"timezone": "UTC",
"agenda": "Test Agenda",
"created_at": "2022-01-21T09:08:12Z",
"join_url": "..."
}
]
}Use Refresh Token
Access token has expiry period of 1 hour and refresh token can last for 15 years.
This means that if we have valid access token and refresh token, even when access token expires, we can always issue new one using refresh token until refresh token itself expires.
Important thing to note here is Zoom also issues new refresh token along with new access token. This makes previous refresh token invalid. So, we should always keep both of these tokens up-to-date.
We use API from Zoom OAuth Server to refresh our access token.
For this API, we will need valid refresh token, clientId and clientSecret.
API Url: https://zoom.us/oauth/token
Request Method: POST
Authorization Type: Basic
Here, username is ClientId and password is ClientSecret.
You can use Base64 encoded credential using ClientId and ClientSecret.
JavaString basicAuthEncoded =
Base64.getEncoder().encodeToString((clientId + ":" + clientSecret).getBytes());Node.jsvar basicAuthEncoded = Buffer.from(clientId + ':' + clientSecret).toString('base64');
Query Params:
grant_type: refresh_token
refresh_token: {Refresh token from access token API}
Response:
{
"access_token": "...",
"token_type": "bearer",
"refresh_token": "...",
"expires_in": 3599,
"scope": "meeting:read meeting:write"
}Here, we will have to keep track of both access token and refresh token.
This API will issue us a new access token and a new refresh token. Old refresh token will now become invalid.
Devs are often seen missing this step and complaining about “invalid token” issue in Zoom forum.
Few important points when using Zoom APIs:
- Zoom APIs have daily rate limit. Follow link to know more: https://marketplace.zoom.us/docs/api-reference/rate-limits#rate-limits
- Check the scope of API in Zoom API documentation before using it.
Reference:
https://marketplace.zoom.us/docs/guides/build/oauth-app
Happy learning !
