Server APIs v2
  • Server APIs overview
  • Accessing Server APIs
  • Room signaling
  • Stream mixing
  • Streaming control
  • Cloud recording
  • Server callbacks
  • Return codes
  • API testing

Accessing Server APIs

Last updated:2021-10-25 17:40

1 Request structure

1.1 Service URL format

ZEGO's Cloud Communication Service Server APIs support proximity-based service access globally, which routes the requests to the nearest and optimal access point. For each ZEGO product, a product-specific API base URL ${SERVICE}-api.zego.im is provided for global access, which will be resolved based on the region where the request is originated.

At the same time, ZEGO also provides the following region-specific service URLs for each product:

Region API base URL
Mainland China (Shanghai) ${SERVICE}-api-sha.zego.im
Hong Kong, Macau and Taiwan (Hong Kong) ${SERVICE}-api-hkg.zego.im
Europe (Frankfurt) ${SERVICE}-api-fra.zego.im
Western United States (California) ${SERVICE}-api-lax.zego.im
Asia-Pacific (Mumbai) ${SERVICE}-api-bom.zego.im

The ${SERVICE} part in the URLs represents the ZEGO product:

Product ${SERVICE} API base URL
Cloud Communication Service rtc rtc-api.zego.im
Collaborative Online Whiteboard whiteboard whiteboard-api.zego.im
Cloud Recording cloudrecord cloudrecord-api.zego.im

1.2 Communication protocol

For secure communications, all the Server APIs must be accessed via HTTPS requests.

1.3 Request method

The Server APIs support the following HTTP request methods:

  • GET
  • POST
For a GET request, all request parameters (including public parameters and business-related parameters) should be placed in the Query. For a POST request, special and complex parameters can be placed in the Request Body.

2 Public parameters

2.1 Public request parameters

Public request parameters are the parameters that are required for every API request.

Parameter Type Required Description
AppId Uint32 Yes The unique Application ID assigned to your project by ZEGO, which can be obtained from the ZEGO Admin Console.
Signature String Yes The API request signature. Refer to 3 Signing the requests for how to generate an API request signature.
SignatureNonce String Yes A random number.
SignatureVersion String Yes The version of the signature. Default value: 2.0.
Timestamp Int64 Yes Unix timestamp in seconds. A maximum error of 10 minutes is allowed.
IsTest String No Whether the request is made to a testing environment.
  • true:Testing Environment
  • false:Production Environment (the default value)

  • For projects that created in ZEGO Admin Console before 2021-11-30:
    • The AppID, AppSign and other information you get from Admin Console use the testing environment.
    • AppId can be configured based on the environment type and actual business needs.
  • For projects that created in ZEGO Admin Console after 2021-11-30:
    • The AppID, AppSign and other information use the production environment.
    • You must set the parameter to `false` to use the production environment.

Sample request:

https://rtc-api.zego.im/?Action=ForbidLiveStream
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=Pc5WB8gokVn0xfeu%2FZV%2BiNM1dgI%3D
&SignatureVersion=2.0
&IsTest=false

2.2 Public response parameters

All responses to API requests are returned in a unified format, with the returned data in JSON format.

The following public response parameters will be included in the response to every request, regardless of whether the request is successful.

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

Sample response:

{
    "Code":0,
    "Data":{
        "MessageId":"1_1611647493487_29"
    },
    "Message":"success",
    "RequestId":"2237080460466033406"
}

3 Signing the requests

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

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

3.1 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 ZEGO. 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 ZEGO server. To ensure system security, please keep this information strictly confidential.

You can find the AppId and ServerSecret of your project by the following steps:

  1. Log in to ZEGO Admin Console, and you will be directed to the Overview page.
  2. In the My Project section, click Config for the project to enter the Project Configuration page.
  3. In the Basic Information section, you will see the AppId of your project.
  4. In the Basic Information section, click View under Server Secret Keys, and you will see the ServerSecret in the window that pops up.

3.2 Generate a signature

  1. Parameters required to generate a signature
Parameter Description
AppId Application ID. The AppId used to generate the signature for a request must be the same as the one included in the public request parameters of the request (refer to section 2.1 above).
SignatureNonce A room number. The SignatureNonce used to generate the signature for a request must be the same as the one included in the public request parameters of the request (refer to section 2.1 above).
ServerSecret Server secret key. Refer to section 3.1 for how to get the ServerSecret from the ZEGO Admin Console.
Timestamp Unix timestamp of the current time, in seconds. A maximum error of 10 minutes is allowed.

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

  1. Signature algorithm

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

  1. Format of the Signature string

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

3.3 Signature sample code

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

Signature sample code in 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 random hex string of 16 hex digits*/
   nonceByte := make([]byte, 8)
   rand.Read(nonceByte)
   signatureNonce := hex.EncodeToString(nonceByte)
   log.Printf(signatureNonce)
   appId := 12345       //Use the AppID and ServerSecret of your project.
   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))
}
Signature sample code in Python
# -*- coding: UTF-8 -*-
import secrets
import string
import hashlib
import time
#Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
def GenerateSignature(appId, signatureNonce, serverSecret, timestamp):
    str1 = str(appId) + signatureNonce + serverSecret + str(timestamp)
    hash = hashlib.md5()
    hash.update(str1.encode("utf8"))
    signature = hash.hexdigest()
    return signature

def main():
    #Generate a random hex string of 16 hex digits.
    signatureNonce = secrets.token_hex(8)

    #Use the AppID and ServerSecret of your project.
    appId = 12345
    serverSecret = "9193cc662a4c0ec135ec71fb57194b38"
    #Get a Unix timestampe of 10 digits.
    timestamp = int(time.time())
    print(GenerateSignature(appId,signatureNonce,serverSecret,timestamp))

if __name__ == '__main__':
    main()
Signature sample code in Java
import java.security.NoSuchAlgorithmException;
import java.security.SecureRandom;
public class md5{
    /**
     * Convert byte array to hex string.
     * @param bytes: the byte array to be converted.
     * @return: the result hex string.
     */
    public static String bytesToHex(byte[] bytes) {
        StringBuffer md5str = new StringBuffer();
        //Convert each byte of the array into a hex string and concatenate all the converted hex strings into an md5 string. 
        int digital;
        for (int i = 0; i < bytes.length; i++) {
            digital = bytes[i];
            if (digital < 0) {
                digital += 256;
            }
            if (digital < 16) {
                md5str.append("0");
            }
            md5str.append(Integer.toHexString(digital));
        }
        return md5str.toString();
    }
    // Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
    public static String GenerateSignature(long appId, String signatureNonce, String serverSecret, long timestamp){
        String str = String.valueOf(appId) + signatureNonce + serverSecret + String.valueOf(timestamp);
        String signature = "";
        try{
            //Create a MD5 message digest instance.
            MessageDigest md = MessageDigest.getInstance("MD5");
            //Generate a byte array.
            byte[] bytes = md.digest(str.getBytes("utf-8"));
            //Convert each byte of the array into a hex string and concatenate all the converted hex strings into an md5 string. 
            signature = bytesToHex(bytes);
        }catch (Exception e) {
            e.printStackTrace();
        }
        return signature;
    }


    public static void main(String[] args){
        //Generate a random hex string of 16 hex digits.
        byte[] bytes = new byte[8];
        SecureRandom sr = null;
        //Create a cryptographically strong random number generator using the SecureRandom class. 
        try{
            sr = SecureRandom.getInstanceStrong();
        }catch(Exception e){
            e.printStackTrace();
        }
        sr.nextBytes(bytes);
        String signatureNonce = bytesToHex(bytes);
        long appId = 12345L;       //Append an "L" or "l" to the AppId value you get from the ZEGO Admin console to indicate that it is a value of long type. 
        String serverSecret = "9193cc662a4c0ec135ec71fb57194b38";
        long timestamp = System.currentTimeMillis() / 1000L;
        System.out.println(GenerateSignature(appId,signatureNonce,serverSecret,timestamp));
    }
}
Signature sample code in PHP
<?php
function GenerateSignature($appId, $signatureNonce, $serverSecret, $timestamp)
{
    $str = $appId.$signatureNonce.$serverSecret.$timestamp;
    $signature = md5($str);
    return $signature;
}

//Generate a random hex string of 16 hex digits.
$signatureNonce = bin2hex(random_bytes(8));
//Use the AppID and ServerSecret of your project.
$appId = 12345;
$serverSecret = "9193cc662a4c0ec135ec71fb57194b38";
$timestamp = time();
$signature = GenerateSignature($appId, $signatureNonce, $serverSecret, $timestamp);
echo $signature;
?>
Signature sample code in Node.js
const crypto = require('crypto'); 
//Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
function GenerateUASignature(appId, signatureNonce, serverSecret, timeStamp){
    const hash = crypto.createHash('md5'); //Use the MD5 hashing algorithm.
    var str = appId + signatureNonce + serverSecret + timeStamp;
    hash.update(str);
    //hash.digest('hex') indicates that the output is in hex format 
    return hash.digest('hex');
}

var signatureNonce = crypto.randomBytes(8).toString('hex');
//Use the AppID and ServerSecret of your project.
var appId = 12345;
var serverSecret = "9193cc662a4c0ec135ec71fb57194b38";
var timeStamp = Date.now();
console.log(GenerateUASignature(appId, signatureNonce, serverSecret, timeStamp));

3.4 Signature failures

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

Return code Description
100000004 Signature expired.
100000005 Invalid signature.