Accessing Server APIs

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.

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

Note

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

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

Copied!

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",
    ......
}

Copied!

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.

Note

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

Signature sample code in Python

Signature sample code in Java

Signature sample code in PHP

Signature sample code in Node.js

Signing failures

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

return code	description
100000004	Signature expired.
100000005	Invalid signature.