Using the Custom Connector app

The Custom Connector app is an advanced tool that facilitates seamless connections to third-party applications through REST APIs. With custom connectors, Admins can easily authenticate their third-party applications, granting them access to a wealth of data and functionality that can be seamlessly integrated into Zoom Contact Center and Zoom Virtual Agent flow editors.

After following this article, you can customize the Connector widget using the flow editor.

This article covers:

• How to access the Custom Connector app
  • Accessing the app from the Zoom App Marketplace
  • Accessing the app from the Manage Connectors page
• How to create a custom connector
• How to set authorization parameters for your connector
• How to add a route
• How to map input variables
• How to map output variables
• How to preview and test your route

Prerequisites for using the Custom Connector app

• Zoom Contact Center or Zoom Virtual Agent license
• Account owner or admin privileges
• This feature must be enabled by Zoom Support. Learn how to contact Zoom Support.

Important:

• The Custom Connector requires knowledge of web development and REST APIs. You also need access to your third-party application’s REST API.
• Zoom does not provide technical support for third-party APIs. If you need help with a third-party API, contact the third-party vendor or your IT admin that manages the application.

How to access the Custom Connector app

The Custom Connector app allows you to conveniently access and manage your connectors. You can access custom connector apps from two different places: the Marketplace and the Manage Connectors section.

Accessing the app from the Zoom App Marketplace

1. Sign in to the Zoom App Marketplace using admin credentials.
2. Use the search box to find the Custom Connector app.
3. Click on the app's icon or name to access it.

Accessing the app from the Manage Connectors page

1. Sign in to the Zoom App Marketplace using admin credentials.
2. In the top-right corner, click Manage.
3. In the Admin App Management section, click Manage Connectors.

How to create a custom connector

1. Follow the previous section to access the Custom Connector app.
2. If you’ve accessed the app from the Marketplace, click Create Connector. If you accessed the app from the Manage Connectors page, click Add Connector then Custom.
3. Enter the following information. Both fields are required:
   • Connector Name: Provide a unique and descriptive name for your connector. This will help you identify the connector easily when managing multiple connections.
   • Zoom Products: Select the specific Zoom products which will have access to the connector.
     Note: Currently, Zoom Contact Center and Zoom Virtual Agent are supported.
4. Click Next and follow the next section to set authorization parameters.

How to set authorization parameters for your connector

1. In the Authorize page, enter the following authorization parameters:
   • Base URL: Provide the Base URL of the third-party API you wish to connect to. This URL will serve as the foundation for all subsequent API requests.
   • Authentication Type: Choose the appropriate authentication type from the provided options. Refer to your third-party API reference to determine the appropriate authentication type.
     • API Key
     • Bearer Token
     • Basic Auth
     • OAuth2 Client Credentials
     • OAuth2 Password Credentials
     • OAuth2 Authorization code
   • Key / Value: Enter the authorization key and value.
   • Add To: Select the location to add the key and value to.
2. Fill in the other fields as required.
3. Click Save.

How to add a route

Routes are the building blocks of a connector, enabling you to define specific actions or operations that the connector can perform. Each route represents a unique REST API endpoint that your connector can interact with. By creating routes, you can design a more versatile and customizable connector.

1. Follow the sections to create a connection and set authorization.
2. Sign in to the Zoom App Marketplace using admin credentials.
3. In the top-right corner, click Manage.
4. In the Admin App Management section, click Manage Connectors.
5. Locate your custom connection.
6. Click the ellipses icon next to your connector, then click Manage Routes.
7. In the top-right corner of the route management page, click Add Route.
8. Enter the following information:
   • Route Name: Provide a unique and descriptive name for the new route. This name will be used to identify the route within the connector.
   • Relative Path: Enter the relative path for the route's API endpoint. For example, if your connector's base URL is https://api.example.com, and the API has a route for retrieving user information, the relative path could be /users. The full endpoint URL is displayed next to URL Preview after you enter the relative path.
   • Path Parameters (Optional): If you added any path parameters to the relative path above, these parameters will be listed in this section. Path parameters are placeholders in the URL that are replaced with actual values when making API calls. For example, if your route has a path parameter for the user ID, you could enter it as {userId}. Path parameters are added in the relative path above using the following notation :parameter.
     Note: You must add path parameters directly to the relative path URL.
   • Query Parameters (Optional): If the route requires any query parameters to be included in the API call, specify them by clicking Add Parameter. You can also add query parameters directly to the relative path, causing the parameters to automatically appear in this section. Query parameters are key-value pairs added to the URL after the ? symbol. For example, if your route supports filtering by date, you could have a query parameter date.
     Add the following information for each query parameter:
     • Parameter: Enter the parameter name as define by the third-party REST API.
     • Data Type: Select the data type of the parameter value.
     • Display Name: Enter a display name to show in Zoom products that the connector has access to.
   • Headers (Optional): If the route requires any specific headers to be included in the API request, click Add Header and enter the key/value pairs. Headers are additional information sent along with the request, such as authentication tokens or content types.
9. Click Next and follow the next section to map input variables.

How to map Input Variables

Once you've added a new route, you need to assign names to your input variables, so they can be easily identified in Zoom Contact Center and Zoom Virtual Agent flows.

1. Understand API Input Schema: Review your API documentation or specification to understand the expected input data format. Identify the required and optional fields, data types, and any specific constraints.
2. Map schema variables by parsing the input JSON schema or manually defining input variables:
   • Parse JSON schema: Enter the JSON schema in the text box, then click Parse JSON Schema to automatically parse the schema and define the input variables. You can then customize the parameters as needed.
   • Define Input Variables: Click Add Parameter to add the necessary input variables that correspond to the fields in the API's input schema. For example, if the API requires a "name” and "email" in the input data, create input variables with appropriate names and data types (for example, Name and Email with the data type as String). Connect the input variables to the appropriate display name within the Route. These routes should trigger the API calls with the input data provided by the flow editor in Zoom Contact Center or Zoom Virtual Agent.

How to map output variables

Output variables represent the data that the connector returns after executing the route.

1. Understand API Output Schema: Review the API documentation or specification to understand the format of the response data. Identify the key data points you want to capture and work with in the flow.
2. Map schema variables by parsing the input JSON schema or manually defining input variables:
   • Parse JSON schema: Enter the JSON schema in the text box, then click Parse JSON Schema to automatically parse the schema and define the output variables. You can then customize the parameters as needed.
   • Define output variables: Add the necessary output variables that correspond to the relevant data points in the API's output schema. For example, if the API returns status, message, and data, you can create output variables to capture these values and relate them to display names which will get used by the flow editor in Zoom Contact Center or Zoom Virtual Agent.

Note:

• If you are dealing with a complex output which you would like to process in the flow editor, select the Raw response option. This sends the response as a string to the flow editor to later process in a JavaScript widget.
• There is a limit of 3,000 characters for the response body that can be sent to the flow.

How to preview and test your route

After mapping variables, you can verify all the details you have configured for your route.

In the Preview and Test page, click Test Route. The JSON response will be displayed.