Example: OAuth Configuration for RingCentral

This guide explains how to:

• Integrate an Algo device with RingCentral using OAuth

• Verify the configuration by sending a test message to a RingCentral team

• Use the OAuth profile to send API calls from an Algo 8450

Note

This document includes third-party configuration procedures that are subject to change. It is provided for reference purposes only, and Algo cannot guarantee that the screenshots or procedures will always be current or up to date.

Before you start

Ensure you have a RingCentral account.

Procedure Overview

This procedure includes the following steps:

1. Creating a RingCentral Application

2. Obtaining JWT Assertion

3. Creating an OAuth Authorization Profile

4. Obtaining Your Team ID

5. Testing "HELLO" Message to a RingCentral Team

6. (Optional): Configuring an 8450 Button to Send Messages to a RingCentral Team

Creating a RingCentral Application

Create a RingCentral application and obtain the required credentials for OAuth. RingCentral applications act as OAuth clients that generate credentials, define scopes, and a redirect URI for authentication.

To create a RingCentral application:

1. Sign in to the RingCentral for Developers.

2. Select Register App.

   

3. Select REST API App, then select Next.

4. Configure App Properties:

   • App Name: Enter an application name.

   • App Description: Enter an application description.

   • Primary Contact: Enter a contact email to receive alerts and notifications related to the application.

5. Configure the Auth settings:

   

   • Select JWT auth flow as the authentication method.

   • Select Yes for Issue refresh tokens?

     Note

     Refresh tokens can expire or become invalid for several reasons, such as revoked app access, password changes, unused tokens, or admin policy restrictions. Refer to the OAuth provider’s documentation for more information. If a refresh token expires or becomes invalid, your automation stops working until OAuth access is reauthorized.

6. Configure the Security settings:

   • Application Scopes: Set to Team Messaging.

   • Who will be authorized to access your app?: Select an option.

     

7. Select Create.

8. After registration, copy these values:

   

   • Client ID

   • Client Secret

     You need this information to configure OAuth later.

Obtaining JWT Assertion

You must generate a signed JSON Web Token (JWT) and send it to the OAuth server to prove your identity.

To obtain a JWT assertion:

1. Sign in to the RingCentral for Developers.

2. On the top-right of the screen, select your profile icon, then select Credentials.

   

3. Select Create JWT.

   

4. Follow the on-screen instructions to configure the basic information for your JWT, then select Create JWT.

   

5. Copy your JWT assertion.

   

Creating an OAuth Authorization Profile

Create an OAuth profile to store your RingCentral authentication settings.

Ensure you have the following:

• Client ID

• Client Secret

• JWT assertion

To create RingCentral OAuth Profile:

1. Log in to your device’s web interface using HTTPS.

   HTTPS is required by RingCentral OAuth process.

2. Go to the Advanced Settings → OAuth.

3. Set a Name for your OAuth profile.

4. Select RINGCENTRAL as the Provider Type.

5. Accept the following automatically populated values:

   • Grant Type: JWT_BEARER

     Token URL: https://platform.ringcentral.com/restapi/oauth/token

   • Client Auth Mode: HTTP_BASIC

   • Scope Mode: NONE

     Note

     You don’t need to enter scope in the OAuth profile. However, you must configure it in your RingCentral application.

   • Extra Params (JSON):

     {
       "environment": "production"
     }

   • JWT Assertion Mode: DISABLED.

6. Configure the following:

   • Client ID: Enter your application’s Client ID.

   • Client Secret: Enter your application’s Client Secret.

   • JWT Assertion/JWT Credential: Enter your account’s JWT assertion.

7. Select Create Profile.

   Your profile appears under the OAuth Profiles list.

Obtaining Your Team ID

You must specify a Team ID to send messages to a RingCentral team.

To find your Team ID:

1. Log in to https://app.ringcentral.com/.

2. Click the More icon on the right of your Team, then select Copy team link.

   The link is formatted like “https://app.ringcentral.com/messages/123456789000”

   Copy the Team ID, which is the number at the end of the URL.

   

   You need the Team ID in your API request payload.

Testing "HELLO" Message to a RingCentral Team

You can test sending messages to the RingCentral team.

Ensure you have the following:

• Team ID

To test sending messages to a RingCentral team:

1. Log in to your device’s web interface using HTTPS.

   HTTPS is required by the RingCentral OAuth process.

2. Go to the Advanced Settings → OAuth.

3. Select your RingCentral profile from the Test OAuth Profile dropdown list.

4. Select RINGCENTRAL as the Provider Type.

5. For the Target URL and Path, use the following string:

   https://platform.ringcentral.com/team-messaging/v1/chats/<Team_ID>/posts

   Replace the <Team_ID> with your actual Team ID.

6. Enter a Data Payload.

   {
   "text": "Hello from OAuth test"
   }

7. Select RUN OAuth Test.

   Upon success:

   • The message is posted to the RingCentral Team.

     
     

     A successful response is displayed.

     

Configuring an 8450 Button to Send Messages to a RingCentral Team

You can configure a button on the Algo 8450 to send messages to a RingCentral team using an existing OAuth profile.

To configure a 8450 button to send messages to a RingCentral team:

1. Create a button on a 8450 screen.

2. Set the Button Status to Enabled.

3. Configure the following:

   • Text: Enter the button display text.

   • Action: Set to Send API Request.

   • Number of API Requests: Set to 1.

   • Request 1 - Command: Set to Other.

   • Request 1 - Method: Set to POST.

   • Request 1 - Custom Path: Set to team-messaging/v1/chats/team_ID/posts.

     Replace the team_ID with your actual Team ID.

   • Request 1 - Targets: Set to platform.ringcentral.com.

   • Request 1 - OAuth Profile: Select your RingCentral profile.

   • Request 1 - Headers: Set to Custom Headers.

   • Request 1 - Custom Headers: Set to Content-Type: application/json; charset=utf-8.

   • Request 1 - Data Payload: You can use the default payload.

     {
        "text": "HELLO!"
     }

4. Select Save.

   Press the button and verify that the message is posted to the RingCentral team.

Troubleshooting

I got a 502 error when I run the OAuth Test

You may be logged out of the device web interface. Log in again and retry.

After I run the “Start Authorization” again, my OAuth Test fails

Each time you run Start Authorization again, select Update Profile to save the new credentials before running the test.

My OAuth profile stops working.

An OAuth profile can stop working if the OAuth provider rejects or invalidates the access or refresh token. Refer to the OAuth provider’s documentation for more information. If this occurs, the OAuth profile must be reauthorized.