--- title: Zoom Configuration slug: zoom-configuration docTags: createdAt: 2021-11-24T01:25:42.000Z --- :::hint{type="info"} Please note that in many circumstances Zoom no longer provides the email addresses for guest visitors. As such is will be important for students to attend the Zoom session with the name that they have recorded in Canvas to ensure a match. ::: ## Overview The Online Meeting Integration tool in aPlus+ allows faculty to connect to Zoom to import meeting attendance where participants can be matched to students in aPlus+. The faculty email address in aPlus+ must match their Zoom user. **Before you get started** The user who completes the setup of the Zoom OAuth application in the Zoom marketplace, MUST be logged in to aPlus+ Attendance admin portal on the same computer. This process cannot be completed by seperate people on seperate computers. In some cases, OAuth Zoom apps can be tied to the user who created them. This means that if in the future the users Zoom account is removed, the OAuth Zoom app they created may also be removed. Please ensure that OAuth Zoom apps have multiple owners to prevent this possibility. **There are the following steps to the configuration:** - In aPlus+ create a connection to Zoom in order to obtain the Redirect URL. - In Zoom, creating an *OAuth App* for the aPlus+ connection using the Redirect URL. - Return to the aPlus+ Zoom connection to set the Client ID and Secret. - In Zoom “install” the app which will authorize aPlus+ to access Zoom. **About OAuth and Zoom Apps** *OAuth* is an open standard which allows a service (Zoom) to provide a third party tool (aPlus+) with access to data on behalf of a Zoom user. Creating an *App* within Zoom is required to provide aPlus+ with access as the app is configured to know about aPlus+, which information can be accessed, and has a shared secret which ensures that only aPlus+ is able to access the Zoom data. In this context, aPlus+ is the *App*, which is connecting to Zoom. ## First create a connection to Zoom from aPlus+ In this step, a connection will be created with a temporary Zoom Client ID and Secret. These will be set later after the Zoom app has been created as they are provided by Zoom. The aPlus+ Zoom connection must be created first in order to obtain the Redirect URL. - Log into aPlus+ as an administrator - Open the Online Meeting Integration page at *Admin > Plug-Ins > Online Meeting Integration* - Click the ‘+ Add connection’ option at the right. - Select “Zoom” as the online meeting platform and click Next. ::Image[]{src="https://api.archbee.com/api/optimize/EKIwCN-iYgDzwOgj04E1V/2gFUZI085ObeNdEPhejMO_image.png" size="88" width="1092" height="147" position="center" showCaption="false"} - The Redirect URL won’t be available until the connection is saved. ::Image[]{src="https://api.archbee.com/api/optimize/EKIwCN-iYgDzwOgj04E1V/AzCIZcnEQC3fi_1znZVxj_image.png" size="88" width="1092" height="597" position="center" showCaption="false"} - Enter a temporary Client ID and Secret and save the connection. - Ensure *Granular Scopes* is selected (not shown in the above screen) - Click on the new connection to open it for editing again. - Make a note of the *Redirect URL* for this connection - this is required to configure Zoom ::Image[]{src="https://api.archbee.com/api/optimize/EKIwCN-iYgDzwOgj04E1V/UNUWquYt7Qrm0S5nn3ekM_image.png" size="88" width="1087" height="286" position="center" showCaption="false"} - You must return to this connection later to update the Client ID and Secret which Zoom will provide for you. - If this is for a shared zoom account, you can specify the email address of that account. This means that all aPlus+ users will access meetings for that Zoom user only. Leave blank for users to access meetings for their own Zoom user. ## Create Zoom App ### Sign in and build App - Navigate to the Zoom *App Marketplace:* [https://marketplace.zoom.us/](https://marketplace.zoom.us/) - Sign in using your Zoom admin credentials. The option will show on the top right. ::Image[]{src="https://api.archbee.com/api/optimize/EKIwCN-iYgDzwOgj04E1V/xnxEAJJqEjypiEMQi0mEI_image.png" size="64" width="702" height="64" position="center" showCaption="false"} - Choose to Build App from the Develop menu ::Image[]{src="https://api.archbee.com/api/optimize/EKIwCN-iYgDzwOgj04E1V/YZ_lGKHo720ha47kYoPlh_image.png" size="64" width="720" height="157" position="center" showCaption="false"} - Create an OAuth app by selecting General App ::Image[]{src="https://api.archbee.com/api/optimize/EKIwCN-iYgDzwOgj04E1V/0J3L_4tTv7a2thTbDDlm__image.png" size="64" width="607" height="572" position="center" showCaption="false"} - \- Select an **Admin-managed. ** (This is required because the user level app API endpoints do not provide enough meeting information) \- Click the *Save* button. ![](https://api.archbee.com/api/optimize/EKIwCN-iYgDzwOgj04E1V/EKo8CSe8ZUirU3Gqykr0d_image.png) - At this point the app will be created and the configuration can be completed by working through the configuration options. ### App Credentials - The **Client ID** and **Client Secret** will be generated for you. These need to be copied and provided to the Zoom connection within aPlus+ which was configured as the first step. - Provide the** OAuth Redirect URL** which you obtained in the first step. - Update the **OAuth Allow List** to match the Redirect URL. - **Click Continue** ![](https://api.archbee.com/api/optimize/EKIwCN-iYgDzwOgj04E1V/vXyWsi6Qq5N17noINNoSn_image.png) ### Access Leave the defaults as they are and select **Continue** ### Surface Leave the defaults as they are and select **Continue** ### Embed Leave the defaults as they are and select **Continue** ### Scopes Add the following scopes Select "Add scopes", then search and add the following: - report\:read\:user\:admin - report\:read\:list\_meeting\_participants\:admin Enter a scope description as follows: *Allows aPlus+ users to connect to Zoom to obtain meeting and participant information for meetings they host.* ** ** ![](https://api.archbee.com/api/optimize/EKIwCN-iYgDzwOgj04E1V/jPZNwbmyjlwtrZHFuptSL_image.png) ### Install This screen allows you to verify that the app has been configured. It may show some error messages if the app is missing some configuration information. Fix those errors then make sure you’re logged into aPlus+ click the *Add* *App Now *button. ![](https://api.archbee.com/api/optimize/EKIwCN-iYgDzwOgj04E1V/HsyJvMsQ_9RJ_JjzfRECh_image.png) You will be asked to authorize the app ***twice***. The scopes are listed to verify the level of access being granted. Click the Allow button to continue. This process only needs to be completed once. ::Image[]{src="https://api.archbee.com/api/optimize/EKIwCN-iYgDzwOgj04E1V/FPt-OmFQEBJfXmaPWZA2U_image.png" size="76" width="645" height="810" position="center" showCaption="false"} The below screen then shows to confirm that the installation is complete. At this time aPlus+ has been granted an access token which enables aPlus+ to ask for the report data from Zoom on behalf of users. With this step complete users can now use the connection to record attendance from Zoom. ::Image[]{src="https://api.archbee.com/api/optimize/EKIwCN-iYgDzwOgj04E1V/xSaiNs6ioK7u11Rmp9JGl_image.png" size="52" width="599" height="107" position="center" showCaption="false"} ## Re-installing the app In the unlikely event that the access token becomes invalid, you can re-install the app at any time by editing the app and clicking the *Add *button again. ## Editing an existing Zoom App Finding an existing app in Zoom in not obvious for infrequent users. Here is how to find it. At the Zoom *App Marketplace:* [https://marketplace.zoom.us/](https://marketplace.zoom.us/) when signed in click the *Manage* option on the top right. ::Image[]{src="https://api.archbee.com/api/optimize/EKIwCN-iYgDzwOgj04E1V/u6gjhRPGR1njpUgwB5Oaj_image.png" size="66" width="652" height="75" position="center" showCaption="false"} View the *Created Apps* page which will list the Zoom app configured for aPlus+ to connect. ::Image[]{src="https://api.archbee.com/api/optimize/EKIwCN-iYgDzwOgj04E1V/vEbmefAhx2WpE3H6iugO3_image.png" size="88" width="1215" height="239" position="center" showCaption="false"} ## Troubleshooting ### Incorrect scopes The below indicates an issue with authorization most likey due to incorrect scopes. Double check the scopes. *Oops! We were unable to compete your request. Please try again (4,700)* ### Unable to get zoom token This is a fundamental issue with the authorization and is likely just incorrect credentials, with the client id and secret are not set correctly in the aPlus+ Zoom connection. Please check the credentials on the Zoom app ‘App Credentials’ screen, and then cross check those with the same in the aPlus+ Zoom connection. ### Invalid Redirect URL An invalid redirect URL error shows when redirected to Zoom. Zoom uses this URL to know which URL to return the user to after authorizing them, and it must match those configured in the Zoom app. This error could occur for a few reasons: - There is a possibility that the redirect url has not propogated through zoom clusters correctly and the solution is to edit your redirect url and change it to something else and then change it back to what it should be. - (Classic Apps) The Whitelist URL specified in the App Credentials area is not specified or not correct. - You are logged into Zoom using a different account than the one the aPlus+ Zoom connection is configured for. ::Image[]{src="https://api.archbee.com/api/optimize/EKIwCN-iYgDzwOgj04E1V/Br0UoMhRPSWinjcEIvHk-_image.png" size="86" width="885" height="239" position="center" showCaption="false"} ### Zoom errors ***Only provide report in recent 6 months* shows when the session you’re recording attendance for occurred more than 6 months ago. ::Image[]{src="https://api.archbee.com/api/optimize/EKIwCN-iYgDzwOgj04E1V/hNnsU5KE_KwjtdvldQhgL_image.png" size="44" width="570" height="137" position="center" showCaption="false"} ***Zoom error 403 Access to the Zoom REST API has been denied for this user. Contact Zoom Support for details* could indicate that the created app no longer exists in the Zoom marketplace. One known situation where this could happen is when the Zoom user who created the app has been removed from Zoom, and the app may be removed automatically. To solve this problem check on the app in the Zoom marketplace, *install* it again (refer to *Install* heading). ::Image[]{src="https://api.archbee.com/api/optimize/EKIwCN-iYgDzwOgj04E1V/h18u2GHglWUQ2SQUPNibv_image.png" size="72" width="968" height="130" position="center" showCaption="false"} ***No meetings to show* means there are no meetings which occurred around the time of the session. Check the information in brackets after the Meetings heading. It can also show if the account is a free Zoom account. ::Image[]{src="https://api.archbee.com/api/optimize/EKIwCN-iYgDzwOgj04E1V/U9a5Ak2VL1wzSmcmDc1MP_image.png" size="68" width="785" height="176" position="center" showCaption="false"} When logging into zoom using a Google account and if using aPlus+ within Canvas, the below refused to connect error page may be shown. This is due to Google not allowing logging in from within an iframe for security purposes. The solution is to either log into Zoom in advance using the same web browser or to open attendance in its own browser tab. ::Image[]{src="https://api.archbee.com/api/optimize/EKIwCN-iYgDzwOgj04E1V/_tG20NVQ_0ilPFOU1Mf-O_image.png" size="52" width="651" height="287" position="center" showCaption="false"} If an authorization or token error shows, the app may need to be re-installed, which is as simple as editing the app in Zoom and clicking the *Install* button again. ## Technical reference ### API Calls The following two API endpoints are called. Each requires the *report\:read\:admin* scope. /v2/report/meetings/\{meetingId}/participants /v2/report/users/\{userId}/meetings ### Notes on user level app API For technical reference only: There are two kinds of app in Zoom, user level and account level. aPlus+ uses the account level app because the user level app endpoints which return meeting information don’t return enough participant information, and to obtain a list of past meetings is cumbersome. The possible calls include: */users/me/meetings* only returns previously “scheduled” meetings so won’t include a “meet now” meeting. */past\_meetings/\{meetingId}/instances* Given a personal meeting ID, returns all instances of meetings using that meeting ID. Without a personal meeting ID, the personal meeting ID which is assigned to a user the meeting ID would need to be obtained from the above meetings endpoint. */past\_meetings/\{meetingUUID}* and */past\_meetings/\{meetingUUID}/participants* only returns name id and email. Configuration and Notes ----------------------- There are some items that need to be completed prior to usage by instructors - Instructor Emails – - *Check that instructors Zoom email address matches their Canvas account emails address.* The Zoom integration uses the instructors email address to filter the correct meetings into their attendance page. This means that their Zoom account email must match the email address that is stored for the instructor in Canvas. - Check the instructor’s emails are currently imported into aPlus+ Attendance. You can do this by: - Opening the admin portal \.aplusattendance.com - Navigating to Admin -> Staff -> Staff List - Set the filter to ‘All Staff’ - Now select edit for a random instructor - Once open, select the ‘Make name, email, etc editable’ - Confirm that the Email field has an email in it - Do not click save! Click cancel to leave. - If the emails are not populated, please contact your account representative and we will check your settings. - Zoom Attendance Status - When the Zoom module is used to mark attendance, it will use the attendance status that is assigned to it. This needs to be defined before the first use. - Whichever status used must NOT be set to hidden or restricted. - (Optional) If you wish to have a specific attendance status setup that is unique to the Zoom integration, you will first need to set that status up in the attendance setting admin page. In the admin portal this can be found under “Admin -> Attendance -> Statuses” - To configure the Zoom attendance status: - Navigate to “Admin -> Plug-ins -> Plug-in Settings" - Expand “Online Meeting Integration”Select the “Attended Status” setting and enter the name of the attended status before selecting save. Its best to copy and paste this from the attendance status setup page, to make sure the name is an exact match. ::Image[]{src="https://api.archbee.com/api/optimize/EKIwCN-iYgDzwOgj04E1V/CK2rV9NbholP3hjEmAhYg_image.png" size="74" width="765" height="89" position="center" showCaption="false"} - Meeting look back days and Meeting look forward days - By default meetings which occur +/- 24 hours of the session date and time will be shown. This can be changed if you need to show meetings which occur earlier than this, relative to the date and time of the session. - To configure: - Navigate to “Admin -> Plug-ins -> Plug-in Settings” - Expand “Online Meeting Integration” - Select the setting to change and enter a number of days. Fractional values are allowed. The settings are “Meeting look back days” and “Meeting look forward days”. Note that the online meeting platform (Zoom) may interpret fractional days to whole days. - How Students are matched aPlus+ attempts to match the Zoom attending students to the course roster, first by their Canvas primary email, and then by name. For the most accurate results *we recommend that students are required to register when joining Zoom sessions, and to use their primary email address that is stored in Canvas*, as that is where aPlus+ gets its email addresses from. ## Support Notes The aPlus+ integration uses the Zoom API, and is constrained by the information provided by that API. We have noticed that if Zoom ‘waiting rooms’ are used, then students will be shown twice in the zoom popup in aPlus+. One for the period in the waiting room, and again for the period after they entered the session.