Wave Administrator Guide

Wave Desktop supports the functions of Wave administrator.

Wave administrator can configure Wave related functions as an enterprise administrator (UCM administrator). Currently, you can configure LiveChat’s Chatbot, view and message records, and enable the third-party integration interface for sending messages.

PREREQUISITES

The UCM administrator should enable the Wave Administrator privileges for the specific extension by accessing the administrator web UI of the UCM, then navigate to Extension/Trunk > Extensions, then on “User Portal/Wave Privileges”, select “Wave Administrator” as shown in the figure below.

OPEN MANAGEMENT PORTAL

Chatbot

To configure the Chatbot feature please refer to the Chatbot Configuration Guide: https://documentation.grandstream.com/knowledge-base/live-chat-chatbot-admin-guide/

Integration

Third-party systems can send notification messages to Wave users through the following interfaces.

For example, the third-party system “Helpdesk” sends notifications to Wave users when there is a new ticket or the ticket status changes, and then the “Helpdesk” system uses the interface to send notification messages to the specified extension or email address.

These extension users can receive notification messages when they log in to the Wave desktop or mobile client, as follows:

Enable Interface Link

To set an Interface Link please follow the steps below:

1. Log in to the Wave client, and the Wave administrator opens the management page in Application > Management Portal > Integration.
2. Click to enable interface link. After enabling, all the following interface links will be valid. Otherwise, all interface links will be invalid.

Add Interface Link

Users can create different interface links for different third-party systems to facilitate the management of the use of third-party systems.

1. Log in to the Wave client, and the Wave administrator opens the management page in Application > Management Portal > Integration > Wave Notification Messages.
2. Click “Add” to add a new interface link.

How to Call the Interface

Third-party systems can call the interface link through the following method to send notification messages to Wave users.

Post:

/gsim/notifyingAssistant/:urlToken

Request example:

curl -i /gsim/notifyingAssistant/:urlToken

Header:

Parameter:

Request Parameter Example:

#!/bin/bash

body='{"to":["1001"],"title":"my title...","description":"my description...","data":"{}","target":"208806031344000888888"}';
secret="my_token"; 
signature=$(echo -n "$body" | openssl -sha256 -hmac "$secret"| awk '{print $2}');
curl -X POST -d "$body" -k "https://c074ad2abcd.a.gdms.cloud/gsim/notifyAssistant/0-aae3e891849641069cfc37ea3d677d98-c074ad2a4b5c" -H "X-Hub-Signature-256: sha256=$signature";

Body Example:

{
	"to": [
		"support@test.com",
		"1001"
	],
	"title": "my title...",
	"description": "my description...",
	"messageType": "json",
	"target":"208806031344000888888",
	"data": "{\"TicketID\":\"123456\",\"TicketNumber\":\"654321\",\"ProductMode\":\"xxx\",  \"TicketTitle\":\"[title]\",\"TicketDescription\":\"[description]\",\"MacAddress\":\"[MAC]\",\"Bug\":\"[bug]\",\"TicketURL\":\"[...]\"}"
} 

Response:

Response Parameter Example:

{
     "im": {
          "action": "notifyAssistant",
          "type": "resp",
          "tid": 1709082631725,
          "errorCode": 0,
          "errorInfo": "success"
     }
}

Error Code List:

Edit/Delete Interface Link

1. Log into Wave Desktop client and open the management page in Application > Management Portal Integration
2. Click the button

   

   to edit the interface link.Only the APP Name and Token can be edited, and the others cannot be edited.

3. Click on the button

   

   to delete the interface. After deletion, the link to this interface will be invalid.

WAVE SSO AUTHENTICATION

Third-party systems can integrate this SSO API (which recognizes Wave accounts) to enable users to sign in to third-party systems using their Wave account simply by clicking a link inside Wave notification messages (“Sign in with Wave” links).

Example:

When a user receives a notification message from a third-party system on Wave and clicks the “Details“ button, the URL will open in a browser (e.g., an OA system). The URL carries the Wave account metadata, allowing the third-party system to decrypt the Wave account information using a secret key, achieving a seamless Single Sign-On (SSO) experience.

1. Go to Management Portal -> SSO Authentication and create a new SSO Authentication API.
   During creation, configure the input parameters as follows:

Parameter Name	Description
Name	Required. A descriptive/remark name for this SSO authentication, such as its intended purpose.
URL Whitelist	Optional. Specifies which URLs are eligible for this SSO authentication parsing. If left blank, any URL using this App ID will automatically be re-assembled to carry Wave account authentication metadata.

Once created successfully, the generated parameters are as follows:

Parameter Name	Description
App ID	Can be used as a URL parameter for the notification message SSO interface link (see steps below).
Secret Key	Used to authenticate the Wave account information within the newly re-assembled URL. The data is stored in JWT format (see steps below).

2. Inject the SSO interface link through the [Add Interface Link]. The link assembly rules are defined below, requiring the inclusion of the SSO appid:

https://xxx.yourcompany.cloud:9443/servlet/sso_login?appid=xxxxxxxxxx&redirect_url=https://gxxx.yourcompany.cloud:9443/v2/indax%3Fembed_url=sys/file/my/index"

3. When a user clicks the details button in the notification message, Wave will construct a new URL and launch it in a web browser:

https://xxx.yourcompany.cloud:9443/servlet/sso_login?redirect_url=https%3A%2F%2Fxxx.yourcompany.cloud%3A9443%2Fv2%2Findax%3Fembed_url%3Dsys%2Ffile%2Fmy%2Findex\u0026login_hint=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBpZCI6ImdkbXNfZGV2IiwiZXhwIjoxNzc0OTQyMTk4LCJleHRlbnNpb24iOiIxMDA1IiwiZmlyc3RfbmFtZSI6ImRkNzQ0N3lhMGQ4Zjh5IiwiaWF0IjoxNzc0OTQyMTM4LCJpc3MiOiJnc2ltIiwibGFzdF9uYW1lIjoiZGQzMGUzeSIsInVzZXJfaWQiOiJkbGxpdUBncmFuZHN0cmVhbS5jbiIsInVzZXJfdHlwZSI6ImVtYWlsIn0.J-nE18DDOdBNmFZ-xYu9HtIi-uvh0o3zNmIeTCN9PDY

4. Third-party systems shall verify and parse user metadata leveraging the login_hint parameter within the URL payload.

JWT follows the standard protocol, and signature verification can be performed using standard procedures.

The commands under Linux are as follows:
JWT="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcHBpZCI6ImdkbXNfZGV2IiwiZXhwIjoxNzc0OTQyMTk4LCJleHRlbnNpb24iOiIxMDA1IiwiZmlyc3RfbmFtZSI6ImRkNzQ0N3lhMGQ4Zjh5IiwiaWF0IjoxNzc0OTQyMTM4LCJpc3MiOiJnc2ltIiwibGFzdF9uYW1lIjoiZGQzMGUzeSIsInVzZXJfaWQiOiJkbGxpdUBncmFuZHN0cmVhbS5jbiIsInVzZXJfdHlwZSI6ImVtYWlsIn0.J-nE18DDOdBNmFZ-xYu9HtIi-uvh0o3zNmIeTCN9PDY"
SECRET="x10KCayFXAMoEMWx0cek57alqyhRkOTD"


HEADER=$(echo $JWT | cut -d '.' -f1)
PAYLOAD=$(echo $JWT | cut -d '.' -f2)
SIGNATURE=$(echo $JWT | cut -d '.' -f3)


LOCAL_SIGN=$(echo -n "$HEADER.$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" -binary | base64 | tr -d '=' | tr '/+' '_-' | tr -d '\n')
echo "Original Signature：$SIGNATURE"echo "Calculated Signature：$LOCAL_SIGN"
if [ "$SIGNATURE" = "$LOCAL_SIGN" ]; then
  echo -e "\n✅ Signature verification successful: JWT is valid and authentic"else
  echo -e "\n❌ Signature verification failed: Signatures do not match."
fi

Parsed payload example:echo $PAYLOAD | base64 -d 2>/dev/null | jq .
{
  "appid": "gdms_dev",
  "exp": 1774942198,
  "extension": "1005",
  "first_name": "dd7447ya0d8f8y",
  "iat": 1774942138,
  "iss": "gsim",
  "last_name": "dd30e3y",
  "user_id": "user123@company123.com",
  "user_type": "email"
}

REFERENCES

Live Chat Chatbot Admin Guide

Wave Desktop – User Guide

Live Chat – User Guide