CallInvite

POST

https://zim-api.zego.im/

This API allows you to create a call invitation in normal mode.

After the call invitation is successfully created, the user who initiated the invitation (caller) will receive a notification that the invitation has been created through the following ZIM SDK callback:

iOS	Android	macOS	Windows
callInvitationCreated	onCallInvitationCreated	callInvitationCreated	onCallInvitationCreated

Web	Mini Program	Flutter	React Native
callInvitationCreated	callInvitationCreated	onCallInvitationCreated	callInvitationCreated

Unity3D	uniapp \| uniapp x	HarmonyOS
onCallInvitationCreated	callInvitationCreated	callInvitationCreated

The invited users (callees) will receive a notification that they have been invited:

iOS	Android	macOS	Windows
callInvitationReceived	onCallInvitationReceived	callInvitationReceived	onCallInvitationReceived

Web	Mini Program	Flutter	React Native
callInvitationReceived	callInvitationReceived	onCallInvitationReceived	callInvitationReceived

Unity3D	uniapp \| uniapp x	HarmonyOS
OnCallInvitationReceived	callInvitationReceived	callInvitationReceived

Note

The users corresponding to the parameters FromUserId and UserIds have logged in to the ZIM service by calling the login method on the client, or the developer has registered the relevant userID by calling the Server API.

Note

The parameters FromUserId and UserIds only support numbers, English characters, and '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', ' ', '{', '}', '|', '~'.

QPS Limit

20 times/s

Request

Query Parameters

Action stringrequired

Possible values: [CallInvite]

API prototype parameter

https://zim-api.zego.im/?Action=CallInvite

AppId uint32required

💡Public parameter. Application ID, assigned by ZEGOCLOUD. Get it from the ZEGOCLOUD Admin Console.

SignatureNonce stringrequired

💡Public parameter. A 16-character hexadecimal random string (hex encoding of 8-byte random number). Refer to Signature example for how to generate.

Timestamp int64required

💡Public parameter. Current Unix timestamp, in seconds. Refer to Signature example for how to generate, with a maximum error of 10 minutes.

SignatureVersion stringrequired

Possible values: [2.0]

Default value: 2.0

💡Public parameter. Signature version number.

Signature stringrequired

💡Public parameter. Signature, used to verify the legitimacy of the request. Refer to Signing the requests for how to generate an API request signature.

application/json

Body

required

FromUserId stringrequired

Possible values: <= 32 characters

Caller user ID (who has logged in to the ZIM service by calling the login method on the client, or has completed registration by calling the Server API).

UserIds string[]required

Possible values: <= 9

List of callee users, with a maximum of 9 users. If you need to increase the limit, please contact ZEGOCLOUD Technical Support.

Timeout number

Possible values: >= 0 and <= 600

Default value: 90

Call timeout period in seconds, with a value range of (0, 600]. If 0 or empty, the default value is 90.

ExtendedData string

Possible values: <= 2048 characters

Extended field, with a maximum length of 2 KB.

OfflinePush objectrequired

Offline push configuration. For details, please refer to MessageBody description - OfflinePush description.

Enable integer

Whether to enable offline push.

1: Enabled;
0: Disabled.

Title string

Title displayed in offline push.

Content string

Content displayed in offline push.

Payload string

Extended field, developers can customize the behavior after receiving offline push messages.

Responses

application/json

Schema
Example (from schema)

Schema

Code integer

Return code.

The following only lists the return codes related to the API business logic. For the complete return codes, please refer to Return codes.

Return code	Description	Suggested Solution
660000002	Parameter error.	Please check the request parameters.
660300005	The call frequency exceeds the AppID-level limit.	Please try again later.
660500002	Operator user is not registered.	Please register the operator user with the ZIM service first.
660900003	All callee users must be registered.	Please check the registration status of the callee users or try again later.
660900007	The callee user list length exceeds the limit.	Please shorten the callee user list length, or contact ZEGOCLOUD Technical Support to increase the limit.

Message string

Operation result description.

RequestId string

Request ID.

CallId string

Call ID.

CreateTime number

Call invitation creation timestamp.

ErrorUsers object[]

Information of users who failed to receive the invitation.When Code is 0:

If ErrorUsers is empty, the invitation was successfully sent to all specified users.
If ErrorUsers is not empty, it means the invitation failed to be sent to some specified users. Please refer to SubCode for handling.

When Code is not 0:

If ErrorUsers is empty, it indicates parameter error, API frequency limit, or system error.
If ErrorUsers is not empty, it means the invitation failed to be sent to all specified users.

Array[

UserId string

Failed user ID.

SubCode number

Specific return code for the failure. The following only lists the return codes related to the API business logic. For the complete return codes, please refer to Return codes.

Return code	Description	Suggested Solution
660000002	Parameter error.	Please check the request parameters.
660300005	The call frequency exceeds the AppID-level limit.	Please try again later.
660500002	Operator user is not registered.	Please register the operator user with the ZIM service first.
660900003	All callee users must be registered.	Please check the registration status of the callee users or try again later.
660900007	The callee user list length exceeds the limit.	Please shorten the callee user list length, or contact ZEGOCLOUD Technical Support to increase the limit.

]

{
  "Code": 0,
  "Message": "success",
  "RequestId": "343649807833778782",
  "CallId": "12261423186766631832",
  "CreateTime": 1713249504000,
  "ErrorUsers": [
    {
      "UserId": "uid2",
      "SubCode": 660500002
    }
  ]
}

{
  "Code": 0,
  "Message": "success",
  "RequestId": "343649807833778782",
  "CallId": "12261423186766631832",
  "CreateTime": 1713249504000,
  "ErrorUsers": [
    {
      "UserId": "uid2",
      "SubCode": 660500002
    }
  ]
}