InviteUsersIntoGroup

POST

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

By calling this API, you can batch add new members to a specified group. A maximum of 100 members can be added at a time. If you need to adjust this limit, please contact ZEGOCLOUD Technical Support.

After successful addition, all group members (including the added users) will receive relevant notifications through the following ZIM SDK callback interfaces:

iOS	Android	macOS	Windows
groupMemberStateChanged	onGroupMemberStateChanged	groupMemberStateChanged	onGroupMemberStateChanged

Web	Mini Program	Flutter	React Native
groupMemberStateChanged	groupMemberStateChanged	onGroupMemberStateChanged	groupMemberStateChanged

Unity3D	uni-app \| uni-app x	HarmonyOS
OnGroupMemberStateChanged	groupMemberStateChanged	groupMemberStateChanged

Note

The users corresponding to the parameters FromUserId and UserId have logged in to the ZIM service by calling the login method on the client, or have completed registration by calling the server-side API.

Note

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

QPS Limit

1 time/s, group-level limit. If you need to adjust this limit, please contact ZEGOCLOUD Technical Support.

Request

Query Parameters

Action stringrequired

Possible values: [InviteUsersIntoGroup]

API prototype parameter

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

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

Operator user ID. The user must be registered with the ZIM service.

GroupId stringrequired

Group ID.

UserIds string[]required

List of user IDs to join the group. By default, a maximum of 100 user IDs are supported.

Note

If the array contains the same value as FromUserId, that value will be removed.

This parameter has the same function as GroupMemberInfos. You can choose either one.

This parameter is only valid when the length of GroupMemberInfos is 0.

GroupMemberInfos object[]required

List of user information to join the group. By default, a maximum of 100 user information entries are supported.This parameter has the same function as UserIds. You can choose either one.

Array[

UserId stringrequired

User ID joining the group.

Note

If this parameter is the same as FromUserId, it will be removed. example: "userA"

EnterGroupTime number

Timestamp for joining the group (in milliseconds).

0 or not passed: Use the current timestamp.
Other: Cannot be greater than the current time.

IsInvite number

Possible values: [0, 1]

User's group joining mode.

0: (Default) Inviting a user can directly pull them into the group without their consent.
1: After receiving an invitation, the user needs to agree before joining the group.

]

Responses

application/json

Schema
Example (from schema)

Schema

Code number

Return code.

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

Code / SubCode	Description	Suggested Solution
660000002	Input parameter error.	Please check the input parameters.
660300006	Frequency limit.	Please try again later or learn about the relevant frequency limits.
660500002	Operator user is not registered.	Please have the operator register with the ZIM service first.
660600001	Group does not exist.	Please confirm if the GroupId is correct.
660000011	Number of users exceeds the limit.	Please check the input user list.

Message string

Description of the operation result.

RequestId string

Request ID.

ErrorUsers object[]

Failure list.

When Code is 0:
If ErrorUsers is empty, all specified users were successfully invited.
If ErrorUsers is not empty, it means some specified users failed to be invited. 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 all specified users failed to be invited.

Array[

UserId string

User ID that failed to be invited.

SubCode number

Return code for invitation failure. For the complete return codes, please refer to the Code description or Return codes.

]

{
  "Code": 0,
  "Message": "success",
  "RequestId": "343649807833778782",
  "ErrorUsers": [
    {
      "UserId": "usera",
      "SubCode": 660000002
    }
  ]
}

{
  "Code": 0,
  "Message": "success",
  "RequestId": "343649807833778782",
  "ErrorUsers": [
    {
      "UserId": "usera",
      "SubCode": 660000002
    }
  ]
}