Accessing Server APIs

Usage Instructions

ZEGOCLOUD Analytics Dashboard Server API supports HTTPS network request protocol, allowing GET or POST methods. You can write code based on the API documentation to access the corresponding API.

Request Method

The Server API request is composed of different content, with a fixed request structure:

Access Address：The access address of the ZEGOCLOUD Analytics Dashboard Server, which is different for different products and regions.
Public Parameters：Each request must have a series of public parameters.
Signature：The signature is also a public parameter, which needs to be generated according to the corresponding signature algorithm.
Request Parameters：You need to specify the target operation through the Action parameter, such as Action = GetBizUsage; you also need to specify other parameters of the interface.

After we verify your signature, we will return the result to you. The interface call will display the return parameters, and the call will display the corresponding error message if it fails. You can analyze and troubleshoot according to global return codes.

Server API Request Example

The following is an example of the request structure for the GetBizUsage (query business scale) interface:

https://analytics-api.zego.im/?Action=GetBizUsage
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=7a2c0f11145fb760d607a07b54825013
&SignatureVersion=2.0
&IsTest=false
&StartDate=20230912
&EndDate=20231012
&Metrics[]=publish_count
&Metrics[]=play_count

https://analytics-api.zego.im/?Action=GetBizUsage
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=7a2c0f11145fb760d607a07b54825013
&SignatureVersion=2.0
&IsTest=false
&StartDate=20230912
&EndDate=20231012
&Metrics[]=publish_count
&Metrics[]=play_count

Where:

https：specifies the request communication protocol.
analytics-api.zego.im：specifies the access address of the ZEGOCLOUD Analytics Dashboard Server.
Action=GetBizUsage：specifies the API to be called.
Public Request Parameters：These are the request parameters that are required for each interface, including AppId、SignatureNonce、Timestamp、Signature、SignatureVersion and IsTest. For details, please refer to [Public Request Parameters](#public request parameters).
Business Parameters：Different Action requires developers to pass in different business parameters. The StartDate、EndDate and Metrics in the above example are business parameters. For details, please refer to the API documentation of each interface.

In addition, ZEGOCLOUD provides example code in multiple programming languages for developers to refer to according to actual circumstances. The following is the Node.js code for the GetBizUsage interface:

const crypto = require('crypto');
const request = require('request');

//Please modify the appId to your AppId, AppId is a number
var appId = 1234567890;
//Please modify the serverSecret to your serverSecret, serverSecret is a string
//Example："1234567890bbc111111da999ef05f0ee"
var serverSecret = ;

//Generate a signature
//Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
function GenerateUASignature(appId, signatureNonce, serverSecret, timeStamp){
    const hash = crypto.createHash('md5'); //Specifies the use of the MD5 algorithm in hash functions
    var str = appId + signatureNonce + serverSecret + timeStamp;
    hash.update(str);
    //hash.digest('hex') indicates that the output format is hexadecimal
    return hash.digest('hex');
}

var signatureNonce = crypto.randomBytes(8).toString('hex');
var timeStamp = Math.round(Date.now()/1000);
// Generate a signature
// The Timestamp used for generating the signature must be consistent with the Timestamp in the URL parameters, and the SignatureNonce used for generating the signature must be consistent with the SignatureNonce in the URL parameters
var sig = GenerateUASignature(appId, signatureNonce, serverSecret, timeStamp)
// analytics-api.zego.im represents the product used is Analytics Dashboard
//The following example can get the number of users in the room with RoomID room1
var url = `https://analytics-api.zego.im/?Action=GetBizUsage&StartDate=20250110&EndDate=20250112&Metrics[]=publish_count&Metrics[]=play_count&AppId=${appId}&SignatureNonce=${signatureNonce}&Timestamp=${timeStamp}&Signature=${sig}&SignatureVersion=2.0&IsTest=false`;

request(url, function(error, response, body){
    console.log('Url: ',url)
    console.log('StatusCode: ',response.statusCode)
    console.log('Error: ', error)
    if(!error && response.statusCode){
        console.log(body)
    }
})

const crypto = require('crypto');
const request = require('request');

//Please modify the appId to your AppId, AppId is a number
var appId = 1234567890;
//Please modify the serverSecret to your serverSecret, serverSecret is a string
//Example："1234567890bbc111111da999ef05f0ee"
var serverSecret = ;

//Generate a signature
//Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
function GenerateUASignature(appId, signatureNonce, serverSecret, timeStamp){
    const hash = crypto.createHash('md5'); //Specifies the use of the MD5 algorithm in hash functions
    var str = appId + signatureNonce + serverSecret + timeStamp;
    hash.update(str);
    //hash.digest('hex') indicates that the output format is hexadecimal
    return hash.digest('hex');
}

var signatureNonce = crypto.randomBytes(8).toString('hex');
var timeStamp = Math.round(Date.now()/1000);
// Generate a signature
// The Timestamp used for generating the signature must be consistent with the Timestamp in the URL parameters, and the SignatureNonce used for generating the signature must be consistent with the SignatureNonce in the URL parameters
var sig = GenerateUASignature(appId, signatureNonce, serverSecret, timeStamp)
// analytics-api.zego.im represents the product used is Analytics Dashboard
//The following example can get the number of users in the room with RoomID room1
var url = `https://analytics-api.zego.im/?Action=GetBizUsage&StartDate=20250110&EndDate=20250112&Metrics[]=publish_count&Metrics[]=play_count&AppId=${appId}&SignatureNonce=${signatureNonce}&Timestamp=${timeStamp}&Signature=${sig}&SignatureVersion=2.0&IsTest=false`;

request(url, function(error, response, body){
    console.log('Url: ',url)
    console.log('StatusCode: ',response.statusCode)
    console.log('Error: ', error)
    if(!error && response.statusCode){
        console.log(body)
    }
})

Request Structure

Access Address

Developers need to specify the corresponding access address based on the geographical region of their server when sending requests to the ZEGOCLOUD Analytics Dashboard Server.

Warning

To ensure the quality of your business service access, please prioritize using the domain name of the geographical region where your server is located as the access address when sending requests to the ZEGOCLOUD Analytics Dashboard Server.

ZEGOCLOUD Analytics Dashboard Server supports request access from the following geographical regions:

Geographical Region	Access Address
Chinese Mainland (Shanghai)	analytics-api-sha.zego.im
Hong Kong, Macau and Taiwan (Hong Kong)	analytics-api-hkg.zego.im
Europe (Frankfurt)	analytics-api-fra.zego.im
Western United States (California)	analytics-api-lax.zego.im
Asia-Pacific (Mumbai)	analytics-api-bom.zego.im
Southeast Asia (Singapore)	analytics-api-sgp.zego.im
Unified access address (regardless of region)	analytics-api.zego.im

Communication Protocol

All ZEGOCLOUD Analytics Dashboard Server API interfaces communicate via HTTPS, providing secure communication services.

Request Method

ZEGOCLOUD Analytics Dashboard Server API supports the following HTTP request methods:

GET
- All request parameters (including public parameters and business parameters) are placed in the Query.
POST
- Special and complex API business parameters are placed in the Body, and public parameters are placed in the Query.
- The parameters in the Body can be directly passed in JsonObject format, without the need to serialize them into String format.
- Set “Content-type” to “application/json” in the Headers.

Public Parameters

This section introduces the public parameters used by developers when calling the ZEGOCLOUD Analytics Dashboard Server API, including public request parameters and public return parameters.

Public Request Parameters

Public request parameters are the request parameters that are required for each interface.

Parameter	Type	Required	Description
AppId	Uint32	Yes	AppId, the unique credential assigned by ZEGOCLOUD.
Signature	String	Yes	Signature, please refer to signature mechanism for signature generation.
SignatureNonce	String	Yes	Random string.
SignatureVersion	String	Yes	Signature version, must be filled in as 2.0.
Timestamp	Int64	Yes	Unix timestamp in seconds. Allow up to 10 minutes of error.
IsTest	String	Yes (for projects created before 2021-11-16)	Whether it is a test environment. The values are as follows: true (case-insensitive): test environment false (case-insensitive): formal environment (default value) Warning For projects created before 2021-11-16 in the ZEGOCLOUD console: The AppId and AppSign obtained from the console are by default in the test environment. This parameter can be set based on the environment type of the AppId and business requirements.
IsTest	String	No (for projects created after 2021-11-16)	Whether it is a test environment. The default is formal environment, and can be ignored and not filled. Warning For projects created after 2021-11-16 in the ZEGOCLOUD console: The AppId and AppSign obtained from the console are all in the formal environment.

Request example:

Warning

Please do not directly copy the following examples for requests.
https://analytics-api.zego.im/?Action=GetBizUsage needs to be replaced with the request address in the "Request method and endpoint" section of each API document.
Modify the values of each common parameter according to the actual situation.

GET

https://analytics-api.zego.im/?Action=xxxx
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=xxxx
&SignatureVersion=2.0
&IsTest=false
&<Non-common request parameters>

https://analytics-api.zego.im/?Action=xxxx
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=xxxx
&SignatureVersion=2.0
&IsTest=false
&<Non-common request parameters>

Public Return Parameters

The API returns results in a unified format, and the data format returned is JSON.

Every time an interface is called, whether successful or not, common parameters will be returned.

Parameter	Type	Description
Code	Number	Return code.
Message	String	Operation result description.
RequestId	String	Request ID.
Data	-	Response data.

Response example:

{
    "Code": 0,
    "Data": {
        "Metrics": [
            {
                "Metric": "publish_count",
                "Values": [
                    {
                        "Date": "20250110",
                        "Value": 100
                    },
                    {
                        "Date": "20250111",
                        "Value": 30
                    },
                    {
                        "Date": "20250112",
                        "Value": 40
                    }
                ]
            },
            {
                "Metric": "play_count",
                "Values": [
                    {
                        "Date": "20250110",
                        "Value": 60
                    },
                    {
                        "Date": "20250111",
                        "Value": 20
                    },
                    {
                        "Date": "20250112",
                        "Value": 10
                    }
                ]
            }
        ]
    },
    "Message": "success",
    "RequestId": 1659512998878671000
}

{
    "Code": 0,
    "Data": {
        "Metrics": [
            {
                "Metric": "publish_count",
                "Values": [
                    {
                        "Date": "20250110",
                        "Value": 100
                    },
                    {
                        "Date": "20250111",
                        "Value": 30
                    },
                    {
                        "Date": "20250112",
                        "Value": 40
                    }
                ]
            },
            {
                "Metric": "play_count",
                "Values": [
                    {
                        "Date": "20250110",
                        "Value": 60
                    },
                    {
                        "Date": "20250111",
                        "Value": 20
                    },
                    {
                        "Date": "20250112",
                        "Value": 10
                    }
                ]
            }
        ]
    },
    "Message": "success",
    "RequestId": 1659512998878671000
}

Signing the requests

To ensure secure API calls, the ZEGOCLOUD server authenticates every API request, which means a request signature must be included in every API request.

Warning

A new signature needs to be generated for every API request.

Get the AppId and Server Secret Key

To generate a request signature, you will need to use the AppId and ServerSecret assigned to your project by ZEGOCLOUD. The AppId is used as the identifier of the request sender, and ServerSecret is the secret key to generate the signature string on the request sender side and verify the signature on the ZEGOCLOUD server. To ensure system security, please keep this information strictly confidential.

You can find the AppId and ServerSecret of your project in the ZEGOCLOUD Admin Console.

Generate a signature

Parameters required to generate a signature

Parameter	Description
AppId	Application ID.
SignatureNonce	A random string.
ServerSecret	Server secret key.
Timestamp	Unix timestamp of the current time, in seconds. A maximum error of 10 minutes is allowed.

Parameter	Description
AppId	Application ID. The AppId in the public parameters. Get it from the ZEGOCLOUD Admin Console.
SignatureNonce	A 16-character hexadecimal random string (hex encoding of 8-byte random number). The SignatureNonce in the public parameters. Refer to Signature sample code for how to generate.
ServerSecret	Server secret key. Get it from the ZEGOCLOUD Admin Console.
Timestamp	Unix timestamp of the current time, in seconds. Refer to Signature sample code for how to generate, with a maximum error of 10 minutes.

Note

The values of the SignatureNonce and Timestamp parameters used to generate the signature must be consistent with those of the common parameters.

Signature algorithm

Signature = md5(AppId + SignatureNonce + ServerSecret + Timestamp)

Format of the Signature string

The Signature is a hex string of 32 characters in lower case.

Signature sample code

ZEGOCLOUD provides sample code in various programming languages for generating the signature.

Go

import (
   "crypto/md5"
   "crypto/rand"
   "encoding/hex"
   "fmt"
   "log"
   "time"
)
// Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
func GenerateSignature(appId uint32, signatureNonce string, serverSecret string, timestamp int64) (Signature string){
   data := fmt.Sprintf("%d%s%s%d", appId, signatureNonce, serverSecret, timestamp)
   h := md5.New()
   h.Write([]byte(data))
   return hex.EncodeToString(h.Sum(nil))
}
func main() {
   /* Generate a 16-character random hexadecimal string (16 bits) */
   nonceByte := make([]byte, 8)
   rand.Read(nonceByte)
   signatureNonce := hex.EncodeToString(nonceByte)
   log.Printf(signatureNonce)
   appId := 12345       // Use your appId and serverSecret
   serverSecret := "9193cc662a4c0ec135ec71fb57194b38"
   timestamp := time.Now().Unix()
   /* appId:12345
      signatureNonce:4fd24687296dd9f3
      serverSecret:9193cc662a4c0ec135ec71fb57194b38
      timestamp:1615186943      2021/03/08 15:02:23
      signature:43e5cfcca828314675f91b001390566a
    */
   log.Printf("signature:%v", GenerateSignature(uint32(appId), signatureNonce, serverSecret, timestamp))
}

import (
   "crypto/md5"
   "crypto/rand"
   "encoding/hex"
   "fmt"
   "log"
   "time"
)
// Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
func GenerateSignature(appId uint32, signatureNonce string, serverSecret string, timestamp int64) (Signature string){
   data := fmt.Sprintf("%d%s%s%d", appId, signatureNonce, serverSecret, timestamp)
   h := md5.New()
   h.Write([]byte(data))
   return hex.EncodeToString(h.Sum(nil))
}
func main() {
   /* Generate a 16-character random hexadecimal string (16 bits) */
   nonceByte := make([]byte, 8)
   rand.Read(nonceByte)
   signatureNonce := hex.EncodeToString(nonceByte)
   log.Printf(signatureNonce)
   appId := 12345       // Use your appId and serverSecret
   serverSecret := "9193cc662a4c0ec135ec71fb57194b38"
   timestamp := time.Now().Unix()
   /* appId:12345
      signatureNonce:4fd24687296dd9f3
      serverSecret:9193cc662a4c0ec135ec71fb57194b38
      timestamp:1615186943      2021/03/08 15:02:23
      signature:43e5cfcca828314675f91b001390566a
    */
   log.Printf("signature:%v", GenerateSignature(uint32(appId), signatureNonce, serverSecret, timestamp))
}

Signing failures

When a signature verification fails, an error code will be returned.

return code	description
100000004	Signature expired.
100000005	Invalid signature.