ZoomNet

| Release Notes| NuGet (stable) | Feedz.IO (prerelease) | |--------------|----------------|-----------------------| | | | |

About

• The ZoomNet library simplifies connecting with the Zoom.us API and interacting with the various endpoints.
• The library also includes a parser that allows you to process inbound webhook messages sent to you by the Zoom API over HTTP.
• Zoom is working on a new server that will deliver the webhook messages over websockets rather than HTTP. This server was introduced in beta during summer 2022 and, as of January 2023, it is still in beta. The ZoomNet library has a convenient client that allows you to receive and process these messages.

Installation

The easiest way to include ZoomNet in your C# project is by adding the nuget package to your project:

PM> Install-Package ZoomNet

.NET framework suport

ZoomNet currently supports:

• .NET framework 4.8
• any framework supporting .NET Standard 2.1 (which includes .NET 5.0 and all subsequent versions as well as some legacy versions such as .NET Core 3.x and ASP.NET Core 3.x).

The last version of ZoomNet that supported .NET 4.6.1, .NET 4.7.2 and .NET Standard 2.0 was 0.35.0

Usage

Creating and Configuring a ZoomNet client

To start using ZoomNet, you need to create an instance of the ZoomClient class. This new instance requires a connection info object which contains information necessary to authenticate you with the Zoom platform. This is discussed in the next section in this document. You can also specify a few optional parameters:

• ZoomClientOptions: settings that control the behavior of the ZoomNet client. If you don't provide an instance of this class, default settings will be used.
• ILogger: logger instance that will receive log messages from the ZoomNet client. If you don't provide an instance of a logger, no log messages will be generated.

[!NOTE] In addition to the default "global" URL, Zoom also offers a half-dozen or so "regional" URLs (such as Canada, EU, India and Australia for example). If you want to use one of these regional base URLs rather than the default global URL, you can specify this in the ZoomClientOptions by invoking one of the convenient methods: WithAustraliaBaseUrl(), WithCanadaBaseUrl(), WithEuropeanUnionBaseUrl(), etc.

Here's a basic example of how to create a ZoomNet client:

    var connectionInfo = ...; // See next section for a discussion about setting up your connection info
    var clientOptions = new ZoomClientOptions().WithCanadaBaseUrl(); // In this example, I'm configuring the client to use Zoom's Canadian URL
	var zoomClient = new ZoomClient(connectionInfo, clientOptions);

You can also optionaly specify one of the following three parameters:

• HttpClient: by default, ZoomNet will create a new instance of HttpClient to send requests to the Zoom API. If you want to manage the lifetime of the HttpClient yourself, you can provide your own instance here.
• IWebProxy: proxy where all requests are routed before being sent to the Zoom API. This is particularly useful if you want to be able to capture every single request for debugging purposes.
• HttpMessageHandler: custom HTTP message handler that will be used by the underlying HttpClient. This is particularly useful for unit testing purposes when you want to mock the requests being sent to the Zoom API.

Connection Information

Before you start using the ZoomNet client, you must decide how you are going to connect to the Zoom API. ZoomNet supports two ways of connecting to Zoom: OAuth and Server-to-Server OAuth.

Connection using OAuth (General App)

The Zoom documentation has a document about how to create an OAuth app and another document about the OAuth autorization flow but I personnality was very confused by the later document so here is a brief step-by-step summary:

• you create an OAuth app, define which permissions your app requires and publish the app to the Zoom marketplace.
• user installs your app. During installation, user is presented with a screen listing the permissons your app requires. User must click accept.
• Zoom generates an "authorization code". This code can be used only once to generate the first access token and refresh token. I CAN'T STRESS THIS ENOUGH: the authorization code can be used only one time. This was the confusing part to me: somehow I didn't understand that this code could be used only one time and I was attempting to use it repeatedly. Zoom would accept the code the first time and would reject it subsequently, which lead to many hours of frustration while trying to figure out why the code was sometimes rejected.
• The access token is valid for 60 minutes and must therefore be "refreshed" periodically.

When you initially add an OAuth application to your Zoom account, you will be issued an "authorization code". You can provide this autorization code to ZoomNet like so:

var clientId = "... your client ID ...";
var clientSecret = "... your client secret ...";
var authorizationCode = "... the code that Zoom issued when you added the OAuth app to your account ...";
var redirectUri = "... the URI you have configured when setting up your OAuth app ..."; // Please note that Zoom sometimes accepts a null value and sometimes rejects it with a 'Redirect URI mismatch' error
var connectionInfo = OAuthConnectionInfo.WithAuthorizationCode(clientId, clientSecret, authorizationCode,
    (newRefreshToken, newAccessToken) =>
    {
        /*
            This callback is invoked when the authorization code
            is converted into an access token and also when the
            access token is subsequently refreshed.

            You should use this callback to save the refresh token
            to a safe place so you can provide it the next time you
            need to instantiate an OAuthConnectionInfo.
            
            The access token on the other hand does not need to be
            preserved because it is ephemeral (meaning it expires
            after 60 minutes). Even if you preserve it, it is very
            likely to be expired (and therefore useless) before the
            next time you need to instantiate an OAuthConnectionInfo.

            For demonstration purposes, here's how you could use your
            operating system's environment variables to store the token:
        */
        Environment.SetEnvironmentVariable("ZOOM_OAUTH_REFRESHTOKEN", newRefreshToken, EnvironmentVariableTarget.User);
    },
    redirectUri);
var zoomClient = new ZoomClient(connectionInfo);

Warning: This sample I just provided can be used only when Zoom issues a new the autorization code. ZoomNet will take care of converting this code into an access token at which point the autorization code is no longer valid.

Once the autorization code is converted into an access token and a refresh token, you can instantiate a 'connection info' object like so:

var clientId = "... your client ID ...";
var clientSecret = "... your client secret ...";
var refreshToken = Environment.GetEnvironmentVariable("ZOOM_OAUTH_REFRESHTOKEN", EnvironmentVariableTarget.User);
var connectionInfo = OAuthConnectionInfo.WithRefreshToken(clientId, clientSecret, refreshToken,
    (newRefreshToken, newAccessToken) =>
    {
        /*
            As previously stated, it's important to preserve the refresh token.
        */
        Environment.SetEnvironmentVariable("ZOOM_OAUTH_REFRESHTOKEN", newRefreshToken, EnvironmentVariableTarget.User);
    });
var zoomClient = new ZoomClient(connectionInfo);

Connection using Server-to-Server OAuth

From Zoom's documentation:

A Server-to-Server OAuth app enables you to securely integrate with Zoom APIs and get your account owner access token without user interaction. This is different from the OAuth app type, which requires user authentication. See Using OAuth 2.0 for details.

ZoomNet takes care of getting a new access token and it also refreshes a previously issued token when it expires (Server-to-Server access token are valid for one hour).

var clientId = "... your client ID ...";
var clientSecret = "... your client secret ...";
var accountId = "... your account id ...";
var connectionInfo = OAuthConnectionInfo.ForServerToServer(clientId, clientSecret, accountId,
    (_, newAccessToken) =>
    {
        /*
            Server-to-Server OAuth does not use a refresh token. That's why I used '_' as the first parameter
            in this delegate declaration. Furthermore, ZoomNet will take care of getting a new access token
            and to refresh it whenever it expires theref