This guide explains how to:
Integrate an Algo device with Cisco Webex using OAuth
Verify the configuration by sending a test message to a Webex space
Use the OAuth profile to send a test message to a Webex space 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 the following:
A Webex account
A Webex space where messages will be posted
Procedure Overview
This procedure includes the following steps:
Creating a Webex Integration
Create a Webex integration and obtain the required credentials for OAuth. Webex integrations act as OAuth clients that generate credentials, define scopes, and a redirect URI for authentication.
To create a Webex Integration:
Sign in to the Webex for Developers.
Select Start Building Apps.
.png)
Select Create an Integration.
.png)
Configure the integration details:
Will this integration use a mobile SDK?: Select No.
Integration name: Enter a name for your application. For example, Algo Device Notifier.
Icon: Choose or upload an icon for your integration.
App Hub Description: Enter a description.
Redirect URI(s): Enter your Algo device’s callback URL using this format: https://<ALGO_DEVICE_IP>/control/oauth-callback.lua
Note
The redirect URI must use HTTPS.
The redirect URI must match exactly in both Webex and your Algo device's configuration.
Scopes: Select spark:all.
Select Add Integration.
After registration, copy these values from the application’s Overview page:
Client ID
Client Secret
You need this information to configure OAuth later.
.png)
Creating an OAuth Authorization Profile
Create an OAuth profile to store your Webex authentication settings.
Ensure you have the following:
Client ID
Client Secret
To create Webex OAuth Profile:
Log in to your device’s web interface using HTTPS.
HTTPS is required by Webex OAuth process.
Go to the Advanced Settings → OAuth.
Set a Name for your OAuth profile.
Select WEBEX as the Provider Type.
Accept the following automatically populated values:
Grant Type: AUTH_CODE_PKCE
Token URL: https://webexapis.com/v1/access_token
Auth URL: https://webexapis.com/v1/authorize
Client Auth Mode: HTTP_BASIC
Scope Mode: SCOPES_LIST
Scope:
spark:allPKCE Method: S256
Response Type: code
Configure the following:
Client ID: Enter your integration’s Client ID.
Client Secret: Enter your integration’s Client Secret.
PKCE Redirect URI: Set to
https://<ALGO_DEVICE_IP>/control/oauth-callback.luaNote
You must use HTTPS in the URI.
Replace <ALGO_DEVICE_IP> with your device IP.
Leave the following fields blank. These values are automatically populated during authorization.
PKCE Authorization Code
PKCE Code Verifier
PKCE Refresh Token
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.
Select START AUTHORIZATION.
Sign in to your Webex account.
.png)
When prompted, select Accept.
.png)
Select Create Profile.
Your profile appears under the OAuth Profiles list.
Finding Your Space ID
You must specify a space ID to send messages.
To find your space ID:
Select Run.
.png)
Sign in to your Webex account if prompted.
In the response, locate your space title under items.
Find the field labeled id corresponding to your space name.
.png)
Copy the value of id.
This is your space ID. You need it in your API request payload.
Testing "HELLO" Message to a Webex Space
You can test sending messages to the Webex space.
Ensure you have the following:
Space ID
To test sending messages to a Webex Space:
Log in to your device’s web interface using HTTPS.
HTTPS is required by Webex OAuth process.
Go to the Advanced Settings → OAuth.
Select your WEBEX profile from the Test OAuth Profile dropdown list.
Select WEBEX as the Provider Type Template.
In the Data Payload, enter your space ID.
{ "roomId": "<space_id>", "text": "HELLO!" }Select RUN OAuth Test.
Upon success:
The message is posted to the Webex space.
A successful response is displayed.
.png)
Configuring an 8450 Button to Send Message to a Webex Space
You can configure a button on the Algo 8450 to send messages to a Webex space using an existing OAuth profile.
.png)
To configure a 8450 button to send messages to a Webex space:
Create a button on a 8450 screen.
Set the Button Status to Enabled.
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
v1/messages.Request 1 - Targets: Set to
webexapis.com.Request 1 - OAuth Profile: Select your Webex 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.
{ "roomId": "<room_id>", "text": "HELLO!" }
Select Save.
Press the button and verify that the message is posted to the Webex channel.
Troubleshooting
I got a 502 error when I run the OAuth Test
You may be logged out of your Algo device’s 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.
.png)
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.