Send a call invitation

Overview

This interface is used to create a call invitation in general mode.

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

iOS	Android	macOS	Windows
callInvitationCreated	onCallInvitationCreated	callInvitationCreated	onCallInvitationCreated
Web	Flutter	React Native
callInvitationCreated	onCallInvitationCreated	callInvitationCreated

The user who is invited (callee) will receive a notification of the invitation:

iOS	Android	macOS	Windows
callInvitationReceived	onCallInvitationReceived	callInvitationReceived	onCallInvitationReceived
Web	Flutter	Unity3D	React Native
callInvitationReceived	onCallInvitationReceived	OnCallInvitationReceived	callInvitationReceived

Request method and endpoint

Request method: POST
Request URL: https://zim-api.zego.im/?Action=CallInvite
Protocol: HTTPS
QPS limit: 20 requests/second

Request parameters

The following list only shows the request parameters for this interface and some common parameters. For a complete list of common parameters, please refer to Accessing Server APIs - Common parameters.

Parameter	Type	Required	Description
FromUserId	String	Yes	The user ID of the caller (registered).
UserIds	Array of String	Yes	A list of user IDs of the callees, with a maximum of 9 users. If you need to increase the limit, please contact ZEGOCLOUD technical support.
Timeout	Number	No	The call timeout period, in seconds, with a value range of (0, 600]. If the value is 0 or empty, the value will be 90 by 90.
ExtendedData	String	No	The extended field, with a maximum length of 2 KB.
OfflinePush	Object	Yes	Offline push configuration, please refer to MessageBody Introduction for the details of offline push parameter.

Note

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

Sample request

Request URL:

https://zim-api.zego.im/?Action=CallInvite
&<Common parameters>

https://zim-api.zego.im/?Action=CallInvite
&<Common parameters>

Request Body:

{
    "FromUserId": "user0",
    "UserIds": [
        "uid1",
        "uid2"
    ],
    "Timeout": 90,
    "ExtendedData": "ExtendedData",
    "OfflinePush": {
        "Enable": 1,
        "Title": "title",
        "Content": "content",
        "Payload": "payload"
    }
}

{
    "FromUserId": "user0",
    "UserIds": [
        "uid1",
        "uid2"
    ],
    "Timeout": 90,
    "ExtendedData": "ExtendedData",
    "OfflinePush": {
        "Enable": 1,
        "Title": "title",
        "Content": "content",
        "Payload": "payload"
    }
}

Response Parameters

Parameter	Type	Description
Code	Number	The return code.
Message	String	The description of the operation result.
RequestId	String	The request ID.
CallId	String	The call ID.
CreateTime	Number	The timestamp when the call invitation was created.
ErrorUsers	Array of Object	Information of users who failed to be invited. Code is 0: ErrorUsers is empty, indicating that the invitation was successfully sent to all specified users. ErrorUsers is not empty, indicating that the invitation failed to be sent to some specified users. Please refer to SubCode for handling. Code is not 0: ErrorUsers is empty, indicating parameter error, interface rate limit, or system error. ErrorUsers is not empty, indicating that the invitation failed to be sent to all specified users.
└UserId	String	The ID of the user who failed to be invited.
└SubCode	Number	The specific return code for the failure.

Response Example

{
    "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
        }
    ] 
}

Return Codes

The following list only shows the return codes related to the business logic of the interface. For a complete list of return codes, please refer to Return codes.

Return Code	Description	Solution
660000002	Invalid parameter.	Check the input parameter.
660300005	The QPS exceeds the AppID level limit.	Try again later.
660500002	The operator is not registered.	Register the operator.
660900003	All callees must be registered.	Check the registration status of the callees or try again later.
660900007	The length of the callees list (`UserIds`) exceeds the limit.	Decrease the callees or contact ZEGOCLOUD technical support to increase the limit.