Platform API

Create group

Use Create group to create an OpenIM group with an owner, initial members and administrators, and group profile data.

HTTP request

POST {API_ADDRESS}/group/create_group

Request example

curl --request POST "${API_ADDRESS}/group/create_group" \
  --header "Content-Type: application/json; charset=utf-8" \
  --header "operationID: ${OPERATION_ID}" \
  --header "token: ${ADMIN_TOKEN}" \
  --data-raw '{
  "memberUserIDs": [
    "user_001",
    "user_002"
  ],
  "adminUserIDs": [
    "user_admin"
  ],
  "ownerUserID": "user_owner",
  "groupInfo": {
    "groupID": "group_001",
    "groupName": "Product Discussion",
    "notification": "Welcome to OpenIM",
    "introduction": "Group for product discussions",
    "faceURL": "https://example.com/group.png",
    "ex": "",
    "groupType": 2,
    "needVerification": 0,
    "lookMemberInfo": 0,
    "applyMemberFriend": 0
  },
  "sendMessage": true
}'

Keep administrator tokens on trusted backend services only. Client applications should use user tokens issued by your backend.

Request body

{
  "memberUserIDs": [
    "user_001",
    "user_002"
  ],
  "adminUserIDs": [
    "user_admin"
  ],
  "ownerUserID": "user_owner",
  "groupInfo": {
    "groupID": "group_001",
    "groupName": "Product Discussion",
    "notification": "Welcome to OpenIM",
    "introduction": "Group for product discussions",
    "faceURL": "https://example.com/group.png",
    "ex": "",
    "groupType": 2,
    "needVerification": 0,
    "lookMemberInfo": 0,
    "applyMemberFriend": 0
  },
  "sendMessage": true
}

Parameter	Required	Type	Description
memberUserIDs	No	array	Initial regular member user IDs, up to 1,000.
adminUserIDs	No	array	List of group administrator user IDs.
ownerUserID	Yes	string	Group owner user ID.
groupInfo	Yes	object	Group profile following `GroupInfo`.
groupInfo.groupID	No	string	Group ID. OpenIM generates one when this field is omitted.
groupInfo.groupName	Yes	string	Group name.
groupInfo.notification	No	string	Group announcement or notification text.
groupInfo.introduction	No	string	Group introduction.
groupInfo.faceURL	No	string	Avatar or icon URL.
groupInfo.ex	No	string	Business extension field.
groupInfo.groupType	Yes	int	Group type. This endpoint requires the value `2`; see `GroupType`.
groupInfo.needVerification	No	int	Join verification policy. See `GroupVerification`.
groupInfo.lookMemberInfo	No	int	Whether members can view group member information.
groupInfo.applyMemberFriend	No	int	Whether members can add each other as friends from the group.
sendMessage	No	boolean	Whether OpenIM should send a notification message for this operation.
displayIsRead Enterprise	No	boolean	Whether group-message read status is displayed. The server may disable it automatically for large groups.

Response

OpenIM usually returns 200 OK when the request reaches the service. Use errCode in the JSON response to determine business success; errCode === 0 means the operation succeeded.

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "groupInfo": {
      "groupID": "group_001",
      "groupName": "Product Discussion",
      "notification": "Welcome to OpenIM",
      "introduction": "Group for product discussions",
      "faceURL": "https://example.com/group.png",
      "ownerUserID": "user_owner",
      "createTime": 1719800000000,
      "memberCount": 3,
      "ex": "",
      "status": 0,
      "creatorUserID": "user_owner",
      "groupType": 2,
      "needVerification": 0,
      "lookMemberInfo": 0,
      "applyMemberFriend": 0,
      "notificationUpdateTime": 0,
      "notificationUserID": ""
    }
  }
}

Response fields

Field	Type	Description
errCode	int	Business error code. `0` means success.
errMsg	string	Short error message.
errDlt	string	Detailed error information for troubleshooting.
data	object	Endpoint-specific response data.
data.groupInfo	object	Created group profile following `GroupInfo`.

Error response

When a request fails, OpenIM returns the same error envelope. See Error codes for the full handling model.

{
  "errCode": 1004,
  "errMsg": "RecordNotFoundError",
  "errDlt": ": [1004]RecordNotFoundError"
}

Scenario	Possible cause	Recommended action
Authentication failed	`token` is missing, expired, or not an administrator token.	Issue a new administrator token and keep it on the backend.
Traceability is weak	`operationID` is missing or reused across many requests.	Generate a unique `operationID` for every request and log it with the response.
Validation failed	The request body has an invalid type, missing field, or unsupported enum value.	Compare the payload with the request table and retry after correcting the fields.

Permissions and limits

groupInfo and ownerUserID are required.
groupInfo.groupType must be 2, and memberUserIDs accepts at most 1,000 users.
displayIsRead is available in OpenIM Enterprise.

Was this page helpful?