Documentation
zim In-app Chat
Documentation
Demo APP
SDK Center
API Center
FAQ
Code Market
Console
Sign Up
Log In
中文站 English
  • Documentation
  • In-app Chat
  • Server APIs
  • Accessing Server APIs

Accessing Server APIs

Last updated:2024-03-14 15:25

Request structure

Service URL format

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

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 server.

ZEGOCLOUD supports request access from the following geographical regions:

Region API base URL
Mainland China (Shanghai)
${PRODUCT}-api-sha.zego.im
Hong Kong, Macau and Taiwan (Hong Kong)
${PRODUCT}-api-hkg.zego.im
Europe (Frankfurt)
${PRODUCT}-api-fra.zego.im
Western United States (California)
${PRODUCT}-api-lax.zego.im
Asia-Pacific (Mumbai)
${PRODUCT}-api-bom.zego.im
Southeast Asia (Singapore)
${PRODUCT}-api-sgp.zego.im
Unified access address (regardless of region)
${PRODUCT}-api.zego.im

In this context, PRODUCT refers to different services provided by ZEGOCLOUD, and in this particular product, it is zim, for instance, zim-api.zego.im.

Communication protocol

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

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.

Public parameters

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 ZEGOCLOUD Admin Console.
Signature
String
Yes
The API request signature. Refer to Signing the requests for how to generate an API request signature.
SignatureNonce
String
Yes
A random string.
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.

Sample request:

https://zim-api.zego.im/?Action=QueryUserOnlineState
&AppId=1234567890
&Timestamp=1234567890
&Signature=Pc5WB8gokVn0xfeu%2FZV%2BiNM1dgI%3D
&SignatureVersion=2.0
&SignatureNonce=15215528852396
&UserId[]=221

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.

Sample response:

{
    "Code": 0,
    "Message": "",
    "RequestId": "8411281679140263090",
    ......
}

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.

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.

The values of the SignatureNonce and Timestamp parameters used to generate the signature must be consistent with those of the public 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.

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 hexadecimal random 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))
}
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 hexadecimal random string (16 bits)
    signatureNonce = secrets.token_hex(8)

    #Use your appId and serverSecret
    appId = 12345
    serverSecret = "9193cc662a4c0ec135ec71fb57194b38"
    #Get 10 digit unix timestamp
    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{
    /**
     * byte array to hexadecimal
     * @param bytes The byte array that needs to be converted
     * @return  Converted Hex string
     */
    public static String bytesToHex(byte[] bytes) {
        StringBuffer md5str = new StringBuffer();
        //Replace each byte of the array into hexadecimal and connect it to 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 an object that provides the information digest algorithm, initialized to the md5 algorithm object
            MessageDigest md = MessageDigest.getInstance("MD5");
            // get byte array after calculation
            byte[] bytes = md.digest(str.getBytes("utf-8"));
            //Replace each byte of the array into hexadecimal and connect it to an md5 string
            signature = bytesToHex(bytes);
        }catch (Exception e) {
            e.printStackTrace();
        }
        return signature;
    }


    public static void main(String[] args){
        //Generate hexadecimal random string (16 bits)
        byte[] bytes = new byte[8];
        SecureRandom sr = null;
        //Use SecureRandom to obtain a high-strength secure random number generator
        try{
            sr = SecureRandom.getInstanceStrong();
        }catch(Exception e){
            e.printStackTrace();
        }
        sr.nextBytes(bytes);
        String signatureNonce = bytesToHex(bytes);
        long appId = 12345L;       //Use your appId and serverSecret, add uppercase L or lowercase l after the number to indicate 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 hexadecimal random string (16 bits)
$signatureNonce = bin2hex(random_bytes(8));
// use your appId and serverSecret
$appId = 12345;
$serverSecret = "9193cc662a4c0ec135ec71fb57194b38";
$timestamp = time();
$signature = GenerateSignature($appId, $signatureNonce, $serverSecret, $timestamp);
echo $signature;
?>
Signature sample code in Node.js/summary>
const crypto = require('crypto'); 
//Signature=md5(AppId + SignatureNonce + ServerSecret + Timestamp)
function GenerateUASignature(appId, signatureNonce, serverSecret, timeStamp){
    const hash = crypto.createHash('md5'); / / Specify the use of the MD5 algorithm in the hash algorithm
    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');
// use your appId and serverSecret
var appId = 12345;
var serverSecret = "9193cc662a4c0ec135ec71fb57194b38";
var timeStamp = Math.round(Date.now()/1000);
console.log(GenerateUASignature(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.
Page Directory
  • Free trial
  • 提交工单
    咨询集成、功能及报价等问题
    电话咨询
    400 1006 604
    Get Consulting
    Scan Wechat QR code