# Manage group members (/en/api-reference/api-ref/im/chat-group-management/manage-group-members)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

Group member management involves operations such as member creation and deletion. Chat provides multiple APIs for adding and retrieving group members, adding a group administrator, and transferring the group owner.

This page shows how to manage group members by calling the Chat RESTful APIs. Before calling the following methods, ensure that you understand the call frequency limit described in [Limitations](../limitations#call-limit-of-server-sides).

## Common parameters [#common-parameters]

The following table lists common request and response parameters of the Chat RESTful APIs:

### Request parameters [#request-parameters]

| Parameter  | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                          | Required |
| :--------- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `host`     | String | The domain name assigned by the Chat service to access RESTful APIs. For how to get the domain name, see [Get the information of your project](/en/realtime-media/im/get-started/enable#get-the-information-of-the-agora-chat-project).                                                                                                                                                                                                              | Yes      |
| `app_id`   | String | The unique identifier automatically assigned to each project by Agora                                                                                                                                                                                                                                                                                                                                                                                | Yes      |
| `username` | String | The unique login account of the user. The user ID must be 64 characters or less and cannot be empty. The following character sets are supported:* 26 lowercase English letters (a-z)
* 10 numbers (0-9)
* "\_", "-", "."<CalloutContainer type="info">
  <CalloutDescription>
    Do not use any of the 26 uppercase English letters (A-Z). Ensure that each `username` under the same App ID is unique.
  </CalloutDescription>
</CalloutContainer> | Yes      |

### Response parameters [#response-parameters]

| Parameter         | Type   | Description                                                                                          |
| :---------------- | :----- | :--------------------------------------------------------------------------------------------------- |
| `action`          | String | The request method.                                                                                  |
| `organization`    | String | The unique identifier assigned to each company (organization) by the Chat service.                   |
| `application`     | String | A unique internal ID assigned to each app by the Chat service. You can safely ignore this parameter. |
| `applicationName` | String | The unique identifier assigned to each app by the Chat service.                                      |
| `uri`             | String | The request URI.                                                                                     |
| `path`            | String | The request path, which is part of the request URI. You can safely ignore this parameter.            |
| `entities `       | JSON   | The response entity.                                                                                 |
| `data`            | JSON   | The details of the response.                                                                         |
| `timestamp`       | Number | The Unix timestamp (ms) of the HTTP response.                                                        |
| `duration`        | Number | The duration (ms) from when the HTTP request is sent to the time the response is received.           |

## Authorization [#authorization]

Chat RESTful APIs require Bearer HTTP authentication. Every time an HTTP request is sent, the following `Authorization` field must be filled in the request header:

```html
Authorization: Bearer ${YourAppToken}
```

In order to improve the security of the project, Agora uses a token (dynamic key) to authenticate users before they log in to the chat system. Chat RESTful APIs only support authenticating users using app tokens. For details, see [Authentication using App Token](/en/realtime-media/im/build/secure-access-and-authentication/authentication).

## Retrieving group members [#retrieving-group-members]

Retrieves the member list of the specified chat group with pagination.

### HTTP request [#http-request]

```bash
GET https://{host}/app-id/{app_id}/chatgroups/{group_id}/users

// Gets the member list of the group with pagination.
GET https://{host}/app-id/{app_id}/chatgroups/{group_id}/users?pagenum={N}&pagesize={N}
```

#### Path parameter [#path-parameter]

| Parameter  | Type   | Description   | Required |
| :--------- | :----- | :------------ | :------- |
| `group_id` | String | The group ID. | Yes      |

#### Query parameter [#query-parameter]

| Parameter  | Type   | Description                                                                                       | Required |
| :--------- | :----- | :------------------------------------------------------------------------------------------------ | :------- |
| `pagenum`  | Number | The current page number. The query starts from the first page by default.                         | No       |
| `pagesize` | Number | The number of members to retrieve per page. The default value is 10. The value range is \[1,100]. | No       |

For other parameters and detailed descriptions, see [Common parameters](#common-parameters).

#### Request header [#request-header]

| Parameter       | Type   | Description                                                                                                                                                                                      | Required |
| :-------------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Accept`        | String | The parameter type. Set it as `application/json`.                                                                                                                                                | Yes      |
| `Authorization` | String | The authentication token of the user or administrator, in the format of `Bearer ${token}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value. | Yes      |

### HTTP response [#http-response]

#### Response body [#response-body]

If the returned HTTP status code is 200, the request succeeds, and the `data` field in the response body contains the following parameters.

| Parameter | Type   | Description                                                                               |
| :-------- | :----- | :---------------------------------------------------------------------------------------- |
| `owner`   | String | The username of the group owner, for example, `{"owner":"user1"}`.                        |
| `member`  | String | The username of a group admin or regular group member, for example, `{"member":"user2"}`. |
| `count`   | String | The number of group members retrieved at this call of this API.                           |

For other fields and descriptions, see [Common parameters](#common-parameters).

If the returned HTTP status code is not 200, the request fails. You can refer to [Status codes](#code) for possible causes.

### Example [#example]

#### Request example [#request-example]

```bash
curl -X GET -H 'Accept: application/json' 'http://XXXX/app-id/XXXX/chatgroups/10130212061185/users?pagenum=2&pagesize=2' -H 'Authorization: Bearer '
```

#### Response example [#response-example]

```json
{
    "action": "get",
    "application": "527cd7e0-XXXX-XXXX-9f59-ef10ecd81ff0",
    "params": {
        "pagesize": [
          "2"
        ],
        "pagenum": [
          "2"
        ]
    },
    "uri": "http://XXXX/app-id/XXXX/chatgroups/10130212061185/users",
    "entities": [],
    "data": [
    {
            "owner": "user1"
    },
    {
            "member": "user2"
    }
    ],
    "timestamp": 1489074511416,
    "duration": 0,
    "organization": "XXXX",
    "applicationName": "XXXX",
    "count": 2
}
```

## Adding a user to the chat group [#adding-a-user-to-the-chat-group]

Adds the specified user to the chat group. If the user is already a member of the chat group, an error is returned.

### HTTP request [#http-request-1]

```bash
POST https://{host}/app-id/{app_id}/chatgroups/{group_id}/users/{username}
```

#### Path parameter [#path-parameter-1]

| Parameter  | Type   | Description   | Required |
| :--------- | :----- | :------------ | :------- |
| `group_id` | String | The group ID. | Yes      |

For other parameters and detailed descriptions, see [Common parameters](#common-parameters).

#### Request parameters [#request-parameters-1]

| Parameter       | Type   | Description                                                                                                                                                                                      | Required |
| :-------------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Content-Type`  | String | The parameter type. Set it as `application/json`.                                                                                                                                                | Yes      |
| `Accept`        | String | The parameter type. Set it as `application/json`.                                                                                                                                                | Yes      |
| `Authorization` | String | The authentication token of the user or administrator, in the format of `Bearer ${token}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value. | Yes      |

### HTTP response [#http-response-1]

#### Response body [#response-body-1]

If the returned HTTP status code is 200, the request succeeds, and the `data` field in the response body contains the following parameters.

| Parameter | Type    | Description                                                                    |
| :-------- | :------ | :----------------------------------------------------------------------------- |
| `result`  | Boolean | Whether the user is successfully added to the chat group. true: Yes.false: No. |
| `groupid` | String  | The group ID.                                                                  |
| `action`  | String  | The request method.                                                            |
| `user`    | String  | The username added to the chat group.                                          |

For other fields and descriptions, see [Common parameters](#common-parameters).

If the returned HTTP status code is not 200, the request fails. You can refer to [Status codes](#code) for possible causes.

### Example [#example-1]

#### Request example [#request-example-1]

```bash
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer ' 'http://XXXX/app-id/XXXX/chatgroups/66016455491585/users/user4'
```

#### Response example [#response-example-1]

```json
{
    "action": "post",
    "application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
    "uri": "http://XXXX/app-id/XXXX/chatgroups/66016455491585/users/user4",
    "entities": [],
    "data": {
      "result": true,
      "groupid": "66016455491585",
      "action": "add_member",
      "user": "user4"
    },
    "timestamp": 1542364958405,
    "duration": 0,
    "organization": "XXXX",
    "applicationName": "XXXX"
}
```

## Adding multiple users to the chat group [#adding-multiple-users-to-the-chat-group]

Adds multiple users to the specified chat group. You can add a maximum of 60 users into a chat group each time. If the users are already members of the chat group, an error is returned in the response body.

### HTTP request [#http-request-2]

```bash
POST https://{host}/app-id/{app_id}/chatgroups/{chatgroupid}/users
```

#### Path parameter [#path-parameter-2]

| Parameter  | Type   | Description   | Required |
| :--------- | :----- | :------------ | :------- |
| `group_id` | String | The group ID. | Yes      |

For other parameters and detailed descriptions, see [Common parameters](#common-parameters).

#### Request header [#request-header-1]

| Parameter       | Type   | Description                                                                                                                                                                                      | Required |
| :-------------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Content-Type`  | String | The parameter type. Set it as `application/json`.                                                                                                                                                | Yes      |
| `Accept`        | String | The parameter type. Set it as `application/json`.                                                                                                                                                | Yes      |
| `Authorization` | String | The authentication token of the user or administrator, in the format of `Bearer ${token}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value. | Yes      |

#### Request body [#request-body]

| Parameter   | Type  | Description                                                                                  | Required |
| :---------- | :---- | :------------------------------------------------------------------------------------------- | :------- |
| `usernames` | Array | The usernames to add to the chat group. You can pass in a maximum of 60 usernames each time. | Yes      |

### HTTP response [#http-response-2]

#### Response body [#response-body-2]

If the returned HTTP status code is 200, the request succeeds, and the `data` field in the response body contains the following parameters.

| Parameter    | Type   | Description                                         |
| :----------- | :----- | :-------------------------------------------------- |
| `newmembers` | Array  | The array of usernames that are added to the group. |
| `groupid`    | String | The group ID.                                       |
| `action`     | String | The request method.                                 |

For other fields and descriptions, see [Common parameters](#common-parameters).

If the returned HTTP status code is not 200, the request fails. You can refer to [Status codes](#code) for possible causes.

### Example [#example-2]

#### Request example [#request-example-2]

```bash
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '{
    "usernames": [
      "user4","user5"
    ]
}' 'http://XXXX/app-id/XXXX/chatgroups/66016455491585/users'
```

#### Response example [#response-example-2]

```json
{
    "action": "post",
    "application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
    "uri": "http://XXXX/app-id/XXXX/chatgroups/66016455491585/users",
    "entities": [],
    "data": {
      "newmembers": [
        "user5",
        "user4"
      ],
      "groupid": "66016455491585",
      "action": "add_member"
    },
    "timestamp": 1542365557942,
    "duration": 0,
    "organization": "XXXX",
    "applicationName": "XXXX"
}
```

## Removing a chat group member [#removing-a-chat-group-member]

Removes the specified user from the chat group. If the specified user is not in the chat group, an error is returned.

Once a member is removed from a chat group, they are also removed from all the threads they have joined in this chat group.

### HTTP request [#http-request-3]

```bash
DELETE https://{host}/app-id/{app_id}/chatgroups/{group_id}/users/{username}
```

#### Path parameter [#path-parameter-3]

| Parameter  | Type   | Description   | Required |
| :--------- | :----- | :------------ | :------- |
| `group_id` | String | The group ID. | Yes      |

For other parameters and detailed descriptions, see [Common parameters](#common-parameters).

#### Request header [#request-header-2]

| Parameter       | Type   | Description                                                                                                                                                                                      | Required |
| :-------------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Accept`        | String | The parameter type. Set it as `application/json`.                                                                                                                                                | Yes      |
| `Authorization` | String | The authentication token of the user or administrator, in the format of `Bearer ${token}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value. | Yes      |

### HTTP response [#http-response-3]

#### Response body [#response-body-3]

If the returned HTTP status code is 200, the request succeeds, and the `data` field in the response body contains the following parameters.

| Parameter | Type    | Description                                                                        |
| :-------- | :------ | :--------------------------------------------------------------------------------- |
| `result`  | Boolean | Whether the user is successfully removed from the chat group. true: Yes.false: No. |
| `groupid` | String  | The group ID.                                                                      |
| `action`  | String  | The request method.                                                                |
| `user`    | String  | The usernames removed from the chat group.                                         |

For other fields and descriptions, see [Common parameters](#common-parameters).

If the returned HTTP status code is not 200, the request fails. You can refer to [Status codes](#code) for possible causes.

### Example [#example-3]

#### Request example [#request-example-3]

```bash
curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer ' 'http://XXXX/app-id/XXXX/chatgroups/66016455491585/users/user3'
```

#### Response example [#response-example-3]

```json
{
    "action": "delete",
    "application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
    "uri": "http://XXXX/app-id/XXXX/chatgroups/66016455491585/users/user3",
    "entities": [],
    "data": {
      "result": true,
      "action": "remove_member",
      "user": "user3",
      "groupid": "66016455491585"
    },
    "timestamp": 1542365943067,
    "duration": 0,
    "organization": "XXXX",
    "applicationName": "XXXX"
}
```

## Removing multiple group members [#removing-multiple-group-members]

Removes multiple users from the chat group. You can remove a maximum of 60 members from the chat group each time. If the specified users are not in the group, an error is returned.

Once a member is removed from a chat group, they are also removed from all the threads they have joined in this chat group.

### HTTP request [#http-request-4]

```bash
DELETE https://{host}/app-id/{app_id}/chatgroups/{group_id}/users/{members}
```

#### Path parameter [#path-parameter-4]

| Parameter | Type   | Description                                                                             | Required |
| :-------- | :----- | :-------------------------------------------------------------------------------------- | :------- |
| group\_id | String | The group ID.                                                                           | Yes      |
| members   | String | The usernames of group members separated by the comma (,). For example, `user1, user2`. | Yes      |

For the descriptions of other path parameters, see [Common Parameters](#common-parameters).

#### Request header [#request-header-3]

| Parameter       | Type   | Description                                                                                                                                                                                      | Required |
| :-------------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Accept`        | String | The parameter type. Set it as `application/json`.                                                                                                                                                | Yes      |
| `Authorization` | String | The authentication token of the user or administrator, in the format of `Bearer ${token}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value. | Yes      |

### HTTP response [#http-response-4]

#### Response body [#response-body-4]

If the returned HTTP status code is 200, the request succeeds to and the `data` field in the response body contains the following parameters.

| Parameter | Type    | Description                                                                        |
| :-------- | :------ | :--------------------------------------------------------------------------------- |
| `result`  | Boolean | Whether the user is successfully removed from the chat group. true: Yes.false: No. |
| `groupid` | String  | The group ID.                                                                      |
| `reason`  | String  | The reason why the users fail to be removed from the chat group.                   |
| `action`  | String  | The request method.                                                                |
| `user`    | String  | The usernames removed from the chat group.                                         |

For other fields and descriptions, see [Common parameters](#common-parameters).

If the returned HTTP status code is not 200, the request fails. You can refer to [Status codes](#code) for possible causes.

### Example [#example-4]

#### Request example [#request-example-4]

```bash
curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer ' 'http://XXXX/app-id/XXXX/chatgroups/66016455491585/users/ttestuser0015981,user2,user3'
```

#### Response example [#response-example-4]

```json
{
    "action": "delete",
    "application": "9b848cf0-XXXX-XXXX-b5b8-0f74e8e740f7",
    "uri": "https://XXXX/app-id/XXXX",
    "entities": [],
    "data": [{
        "result": false,
        "action": "remove_member",
        "reason": "user ttestuser0015981 doesn't exist.",
        "user": "user1",
        "groupid": "1433492852257879"
    },
    {
        "result": true,
        "action": "remove_member",
        "user": "user2",
        "groupid": "1433492852257879"
    },
    {
        "result": true,
        "action": "remove_member",
        "user": "user3",
        "groupid": "1433492852257879"
    }],
    "timestamp": 1433492935318,
    "duration": 84,
    "organization": "XXXX",
    "applicationName": "XXXX"
}
```

## Setting custom attributes of a group member [#setting-custom-attributes-of-a-group-member]

Sets the custom attributes of a group member, such as adding a nickname or avatar. Each custom attribute should be in key-value format.

### HTTP request [#http-request-5]

```bash
PUT https://{host}/app-id/{app_id}/metadata/chatgroup/{group_id}/user/{username}
```

#### Path parameter [#path-parameter-5]

| Parameter  | Type   | Description                                                        | Required |
| :--------- | :----- | :----------------------------------------------------------------- | :------- |
| `username` | String | The user ID of a group member for which custom attributes are set. | Yes      |

For other parameters and detailed descriptions, see [Common parameters](#common-parameters).

#### Request header [#request-header-4]

| Parameter       | Type   | Description                                                                                                                                                                                   | Required |
| :-------------- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Content-Type`  | String | The parameter type. Set it as `application/json`.                                                                                                                                             | Yes      |
| `Accept`        | String | The parameter type. Set it as `application/json`.                                                                                                                                             | Yes      |
| `Authorization` | String | The authentication token of the user or administrator, in the format of `Bearer ${YourAppToken}`, where `Bearer` is a fixed character, followed by a space and then the obtained token value. | Yes      |

#### Response body [#response-body-5]

| Parameter  | Type | Description                                                                                                                                                                                                                                                                                                                                                                                      |
| :--------- | :--- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `metaData` | JSON | Custom attributes of a group member to set. Each attribute is represented as a key-value pair:  The key indicates the attribute name and cannot exceed 16 bytes.  The value indicates the attribute value and cannot exceed 512 bytes. Passing an empty string to the value means to delete the attribute.  For a single group member, the total length of custom attributes cannot exceed 4 KB. |

### HTTP response [#http-response-5]

#### Response body [#response-body-6]

If the returned HTTP status code is 200, the request succeeds and the response body contains the following parameters.

| Field  | Type | Description                                       |
| :----- | :--- | :------------------------------------------------ |
| `data` | JSON | Custom attributes of a group member that are set. |

For other fields and descriptions, see [Common parameters](#common-parameters).

If the returned HTTP status code is not 200, the request fails. You can refer to [Status codes](../http-status-codes) for possible causes.

### Example [#example-5]

#### Request example [#request-example-5]

```bash
curl --location --request PUT 'https://XXXX/app-id/XXXX/metadata/chatgroup/207059303858177/user/test2' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
-H 'Authorization: Bearer ' \
-d '{
    "metaData": {
          "key1": "value1"
    }
}'
```

#### Response example [#response-example-5]

```json
{
  "timestamp": 1678674135533,
  "data": {
    "key1": "value1"
  },
  "duration": 53
}
```

## Retrieving all custom attributes of a group member [#retrieving-all-custom-attributes-of-a-group-member]

Retrieves all custom attributes of a group member.

### HTTP request [#http-request-6]

```bash
GET https://{host}/app-id/{app_id}/metadata/chatgroup/{group_id}/user/{username}
```

#### Path parameter [#path-parameter-6]

| Parameter  | Type   | Description                                                                | Required |
| :--------- | :----- | :------------------------------------------------------------------------- | :------- |
| `username` | String | The user ID of a group member whose custom attributes are to be retrieved. | Yes      |

For other parameters and detailed descriptions, see [Common parameters](#common-parameters).

#### Request header [#request-header-5]

| Parameter       | Type   | Description                                                                                                                                                                                             | Required |
| :-------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------- |
| `Content-Type`  | String | The parameter type. Set it as `application/json`.                                                                                                                                                       | Yes      |
| `Accept`        | String | The parameter type. Set it as `application/json`.                                                                                                                                                       | Yes      |
| `Authorization` | String | The authentication token of the user or administrator, in the format of `Bearer ${YourAppToken}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value. | Yes      |

### HTTP response [#http-response-6]

#### Response body [#response-body-7]

If the returned HTTP status code is 200, the request succeeds and the response body will contain the following parameters.

| Field  | Type | Description                                                 |
| :----- | :--- | :---------------------------------------------------------- |
| `data` | JSON | All custom attributes of a group member that are retrieved. |

For other fields and descriptions, see [Common parameters](#common-parameters).

If the returned HTTP status code is not 200, the request fails. You can refer to [Status codes](../http-status-codes) for possible causes.

### Example [#example-6]

#### Request example [#request-example-6]

```bash
curl --location --request GET 'https://XXXX/app-id/XXXX/metadata/chatgroup/207059303858177/user/test2' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
-H 'Authorization: Bearer ' \
-d ''
```

#### Response example [#response-example-6]

```json
{
  "timestamp": 1678674211840,
  "data": {
    "key1": "value1"
  },
  "duration": 6
}
```

## Retrieving custom attributes of multiple group members by attribute key [#retrieving-custom-attributes-of-multiple-group-members-by-attribute-key]

Retrieves custom attributes of multiple group members by attribute key. You can retrieve custom attributes of at most 10 group members each time.

### HTTP request [#http-request-7]

```bash
POST https://{host}/app-id/{app_id}/metadata/chatgroup/{group_id}/get
```

#### Path parameter [#path-parameter-7]

For the parameters and detailed descriptions, see [Common parameters](#common-parameters).

#### Request header [#request-header-6]

| Parameter       | Type   | Description                                                                                                                                                                                             | Required |
| :-------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------- |
| `Content-Type`  | String | The parameter type. Set it as `application/json`.                                                                                                                                                       | Yes      |
| `Accept`        | String | The parameter type. Set it as `application/json`.                                                                                                                                                       | Yes      |
| `Authorization` | String | The authentication token of the user or administrator, in the format of `Bearer ${YourAppToken}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value. | Yes      |

#### Request body [#request-body-1]

| Parameter    | Type       | Description                                                                                                                                                                   | Required |
| :----------- | :--------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `targets`    | JSON Array | The user IDs of group members whose custom attributes are to be retrieved. You can pass in at most 10 user IDs.                                                               | Yes      |
| `properties` | JSON Array | The array of keys of custom attributes to retrieve. If you pass in an empty string or no value to the parameter, all custom attributes of the group members will be returned. | Yes      |

### HTTP response [#http-response-7]

#### Response body [#response-body-8]

If the returned HTTP status code is 200, the request succeeds and the response body will contain the following parameters.

| Field  | Type | Description                                                                                                                                                                                                   |
| :----- | :--- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `data` | JSON | The custom attributes of the group members that are retrieved. As shown in the following response example, `test1` and `test2` are user IDs of group members to which the retrieved custom attributes belong. |

For other fields and descriptions, see [Common parameters](#common-parameters).

If the returned HTTP status code is not 200, the request fails. You can refer to [Status codes](../http-status-codes) for possible causes.

### Example [#example-7]

#### Request example [#request-example-7]

```bash
curl --location --request POST 'https://XXXX/app-id/XXXX/metadata/chatgroup/207059303858177/get' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
-H 'Authorization: Bearer ' \
-d '{
    "targets":["test1","test2"],
    "properties":["key1","key2"]
}'
```

#### Response example [#response-example-7]

```json
{
  "timestamp": 1678674292783,
  "data": {
    "test1": {
      "key1": "value1"
    },
    "test2": {
      "key1": "value1"
    }
  },
  "duration": 2
}
```

## Retrieving group admin list [#retrieving-group-admin-list]

Retrieves the list of the chat group admins.

### HTTP request [#http-request-8]

```bash
GET https://{host}/app-id/{app_id}/chatgroups/{group_id}/admin
```

#### Path parameter [#path-parameter-8]

| Parameter  | Type   | Description   | Required |
| :--------- | :----- | :------------ | :------- |
| `group_id` | String | The group ID. | Yes      |

For other parameters and detailed descriptions, see [Common parameters](#common-parameters).

#### Request header [#request-header-7]

| Parameter       | Type   | Description                                                                                                                                                                                      | Required |
| :-------------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Content-Type`  | String | The parameter type. Set it as `application/json`.                                                                                                                                                | Yes      |
| `Authorization` | String | The authentication token of the user or administrator, in the format of `Bearer ${token}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value. | Yes      |

### HTTP response [#http-response-8]

#### Response body [#response-body-9]

If the returned HTTP status code is 200, the request succeeds, and the `data` field in the response body contains the information of the chat group admins. For other fields and descriptions, see [Common parameters](#common-parameters).

If the returned HTTP status code is not 200, the request fails. You can refer to [Status codes](#code) for possible causes.

### Example [#example-8]

#### Request example [#request-example-8]

```bash
curl -X GET HTTP://XXXX/app-id/XXXX/chatgroups/10130212061185/admin -H 'Authorization: Bearer '
```

#### Response example [#response-example-8]

```json
{
    "action": "get",
    "application": "527cd7e0-XXXX-XXXX-9f59-ef10ecd81ff0",
    "uri": "http://XXXX/app-id/XXXX/chatgroups/10130212061185/admin",
    "entities": [],
    "data": ["user1"],
    "timestamp": 1489073361210,
    "duration": 0,
    "organization": "XXXX",
    "applicationName": "XXXX",
    "count": 1
}
```

## Adding a group admin [#adding-a-group-admin]

Adds a regular group member to the group admin list. A chat group admin has the privilege to manage the chat group blocklist and mute chat group members. You can add a maximum of 99 chat group admins.

### HTTP request [#http-request-9]

```bash
POST https://{host}/app-id/{app_id}/chatgroups/{group_id}/admin
```

#### Path parameter [#path-parameter-9]

| Parameter  | Type   | Description   | Required |
| :--------- | :----- | :------------ | :------- |
| `group_id` | String | The group ID. | Yes      |

For other parameters and detailed descriptions, see [Common parameters](#common-parameters).

#### Request header [#request-header-8]

| Parameter       | Type   | Description                                                                                                                                                                                      | Required |
| :-------------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Content-Type`  | String | The parameter type. Set it as `application/json`.                                                                                                                                                | Yes      |
| `Accept`        | String | The parameter type. Set it as `application/json`.                                                                                                                                                | Yes      |
| `Authorization` | String | The authentication token of the user or administrator, in the format of `Bearer ${token}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value. | Yes      |

#### Request body [#request-body-2]

| Parameter  | Type   | Description                           | Required |
| :--------- | :----- | :------------------------------------ | :------- |
| `newadmin` | String | The username of the chat group admin. | Yes      |

### HTTP response [#http-response-9]

#### Response body [#response-body-10]

If the returned HTTP status code is 200, the request succeeds, and the `data` field in the response body contains the following parameters.

| Parameter | Type   | Description                                         |
| :-------- | :----- | :-------------------------------------------------- |
| `data`    | String | The user IDs promoted to group admins.              |
| `count`   | Number | The number of users to be promoted as group admins. |

For other fields and descriptions, see [Common parameters](#common-parameters).

If the returned HTTP status code is not 200, the request fails. You can refer to [Status codes](#code) for possible causes.

### Example [#example-9]

#### Request example [#request-example-9]

```bash
curl -X POST -H 'Content-type: application/json' -H 'Accept: application/json' 'http://XXXX/app-id/XXXX/chatgroups/10130212061185/admin' -d '{"newadmin":"user1"}' -H 'Authorization: Bearer '
```

#### Response example [#response-example-9]

```json
{
    "action": "post",
    "application": "52XXXXf0",
    "applicationName": "demo",
    "data": {
        "result": "success",
        "newadmin": "man"
    },
    "duration": 0,
    "entities": [],
    "organization": "XXXX",
    "properties": {},
    "timestamp": 1680074570600,
    "uri": "http://XXXX/app-id/XXXX/chatgroups/190141728620545/admin"
}
```

## Removing a group admin [#removing-a-group-admin]

Removes the specified user from the chat group admin list.

### HTTP request [#http-request-10]

```bash
DELETE https://{host}/app-id/{app_id}/chatgroups/{group_id}/admin/{username}
```

#### Path parameter [#path-parameter-10]

| Parameter  | Type   | Description   | Required |
| :--------- | :----- | :------------ | :------- |
| `group_id` | String | The group ID. | Yes      |

For other parameters and detailed descriptions, see [Common parameters](#common-parameters).

#### Request header [#request-header-9]

| Parameter       | Type   | Description                                                                                                                                                                                      | Required |
| :-------------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Accept`        | String | The parameter type. Set it as `application/json`.                                                                                                                                                | Yes      |
| `Authorization` | String | The authentication token of the user or administrator, in the format of `Bearer ${token}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value. | Yes      |

### HTTP response [#http-response-10]

#### Response body [#response-body-11]

If the returned HTTP status code is 200, the request succeeds, and the `data` field in the response body contains the following parameters.

| Parameter  | Type    | Description                                                                                          |
| :--------- | :------ | :--------------------------------------------------------------------------------------------------- |
| `result`   | Boolean | Whether the group admin is successfully demoted to a regular group member: `true`: Yes. `false`: No. |
| `oldadmin` | String  | The ID of the group admin demoted to a regular group member.                                         |

For other fields and descriptions, see [Common parameters](#common-parameters).

If the returned HTTP status code is not 200, the request fails. You can refer to [Status codes](#code) for possible causes.

### Example [#example-10]

#### Request example [#request-example-10]

```bash
curl -X DELETE -H 'Accept: application/json' 'http://XXXX/app-id/XXXX/chatgroups/10130212061185/admin/user1' -H 'Authorization: Bearer '
```

#### Response example [#response-example-10]

```json
{
    "action": "delete",
    "application": "527cd7e0-XXXX-XXXX-9f59-ef10ecd81ff0",
    "uri": "http://XXXX/app-id/XXXX/chatgroups/10130212061185/admin/user1",
    "entities": [],
    "data": {
        "result": "success",
        "oldadmin": "user1"
    },
    "timestamp": 1489073432732,
    "duration": 1,
    "organization": "XXXX",
    "applicationName": "XXXX"
}
```

## Transferring group ownership [#transferring-group-ownership]

Changes the group owner to another group member. Group owners possess all group privileges.

### HTTP request [#http-request-11]

```bash
PUT https://{host}/app-id/{app_id}/chatgroups/{group_id}
```

#### Path parameter [#path-parameter-11]

| Parameter  | Type   | Description   | Required |
| :--------- | :----- | :------------ | :------- |
| `group_id` | String | The group ID. | Yes      |

For other parameters and detailed descriptions, see [Common parameters](#common-parameters).

#### Request header [#request-header-10]

| Parameter       | Type   | Description                                                                                                                                                                                      | Required |
| :-------------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Content-Type`  | String | The parameter type. Set it as `application/json`.                                                                                                                                                | Yes      |
| `Accept`        | String | The parameter type. Set it as `application/json`.                                                                                                                                                | Yes      |
| `Authorization` | String | The authentication token of the user or administrator, in the format of `Bearer ${token}`, where `Bearer` is a fixed character, followed by an English space, and then the obtained token value. | Yes      |

#### Request body [#request-body-3]

| Parameter  | Type   | Description                          | Required |
| :--------- | :----- | :----------------------------------- | :------- |
| `newowner` | String | The username of the new group owner. | Yes      |

### HTTP response [#http-response-11]

#### Response body [#response-body-12]

If the returned HTTP status code is 200, the request succeeds and the `data` field in the response body will contain the following parameters.

| Parameter  | Type    | Description                                                                         |
| :--------- | :------ | :---------------------------------------------------------------------------------- |
| `newowner` | Boolean | Whether the user is successfully set as the chat group owner. true: Yes; false: No. |

For other fields and descriptions, see [Common parameters](#common-parameters).

If the returned HTTP status code is not 200, the request fails. You can refer to [Status codes](#code) for possible causes.

### Example [#example-11]

#### Request example [#request-example-11]

```bash
curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '{     "newowner": "user2"   }' 'http://XXXX/app-id/XXXX/chatgroups/66016455491585'
```

#### Response example [#response-example-11]

```json
{
    "action": "put",
    "application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
    "uri": "http://XXXX/app-id/XXXX/chatgroups/66016455491585",
    "entities": [],
    "data": {
      "newowner": true
    },
    "timestamp": 1542537813420,
    "duration": 0,
    "organization": "XXXX",
    "applicationName": "XXXX"
}
```

## Status codes [#status-codes]

For details, see [HTTP Status Codes](../http-status-codes).