# Create, delete, and retrieve chat groups (/en/api-reference/api-ref/im/chat-group-management/create-delete-retrieve-groups)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
Upon login to Chat, you can create, modify, or delete a group.
This page shows how to create, retrieve, modify, and delete a group by calling 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)
* "\_", "-", "."
Do not use any of the 26 uppercase English letters (A-Z). Ensure that each `username` under the same App ID is unique.
| 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).
## Creating a group [#creating-a-group]
Creates a new group and sets the group information. The group information includes the group name, description, whether the group is public or private, the maximum number of group members (including the group owner), whether a user requesting to join the group requires approval, the group owner, and group members.
### HTTP request [#http-request]
```html
POST https://{host}/app-id/{app_id}/chatgroups
```
#### Path parameter [#path-parameter]
For the descriptions of other path parameters, see [Common Parameters](#param).
#### Request header [#request-header]
| Parameter | Type | Description | Required |
| :-------------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Content-Type` | String | The content type. Set it as `application/json`. | Yes |
| `Accept` | String | The content 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 |
| :-------------------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `groupname` | String | The group name. It cannot exceed 128 characters. | No |
| `avatar` | String | The group avatar URL. It cannot exceed 1024 characters. | No |
| `description` | String | The group description. It cannot exceed 512 characters. | No |
| `public` | Boolean | Whether the group is a public group. Public groups can be searched and chat users can apply to join a public group. Private groups cannot be searched, and chat users can join a private group only if the group owner or admin invites the user to join the group. `true`: Yes. `false`: No | No |
| `maxusers` | String | The maximum number of group members (including the group owner). The default value is `200`. If you set this parameter to a value greater than `3000`, the offline push function is not available to such a large group. To enable the offline push function for a large group, contact [support@agora.io](mailto\:support@agora.io) before creating it. Note that it is impossible to enable the offline push function for a large group that is created. The upper limit varies with your price plans. For details, see [Pricing Plan Details](./agora_chat_plan#group). | No |
| `allowinvites` | Boolean | Whether a regular group member is allowed to invite other users to join the group. `true`: Yes. `false`: (Default) No. Only the group owner or admin can invite other users to join the group. When creating a group, this parameter is only valid for private groups and not for public groups. That is to say, when creating a public group (`public` is set to `true`), even if `allowinvites` is set to `true`, this setting will be automatically modified to `false`. If you want to allow ordinary members of a public group to add people to the group, you can call the \[Modify Group Information]\(#Modify Group Information) interface to modify the setting of `allowinvites` to `true` after creating the group. | No |
| `membersonly` | Boolean | Whether the user requesting to join the public group requires approval from the group owner or admin: `true`: Yes. `false`: (Default) No. The parameter is valid only for public groups as users can only be invited to join private groups and cannot apply to join them. | No |
| `invite_need_confirm` | Boolean | Whether the invitee needs to confirm the received group invitation before joining the group: `true`: Yes. `false`: No. The invitee automatically joins the group after receiving the group invitation. | No |
| `owner` | String | The group owner. | Yes |
| `members` | Array | The array of user IDs of group members, excluding the group owner. The number of user IDs in the array cannot exceed the value of `maxusers`. | No |
| `custom` | String | The extension information of the group. The extension information cannot exceed 8 KB. | No |
### 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 | Descriptions |
| :-------- | :----- | :------------ |
| `groupid` | String | The group ID. |
For other fields and descriptions, see [Common parameters](#param).
If the returned HTTP status code is not 200, the request fails. You can refer to [Status code](#code) table for possible causes.
### Example [#example]
#### Request example [#request-example]
```bash
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer ' -d '{
"groupname": "testgroup",
"avatar": "https://www.XXXX.com/XXX/image",
"description": "test",
"public": true
"maxusers": 300,
"owner": "testuser",
"members": [
"user2"
]
}' 'http://XXXX/app-id/XXXX/chatgroups'
```
#### Response example [#response-example]
```json
{
"action": "post",
"application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
"uri": "http://XXXX/app-id/XXXX/chatgroups",
"entities": [],
"data": {
"groupid": "6602XXXX783617"
},
"timestamp": 1542361730243,
"duration": 0,
"organization": "XXXX",
"applicationName": "XXXX"
}
```
## Banning a group [#banning-a-group]
Bans the specified group. Groups are typically banned when too many users or messages violate community guidelines.
Once a group is banned, the group members in the group can no longer send or receive messages, and the owner and admins cannot perform supervisory operations.
### HTTP request [#http-request-1]
```html
POST https://{host}/app-id/{app_id}/chatgroups/{group_id}/disable
```
#### Path parameter [#path-parameter-1]
For the descriptions of other path parameters, see [Common Parameters](#param).
#### Request header [#request-header-1]
| Parameter | Type | Description | Required |
| :-------------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Content-Type` | String | The content type. Set it as `application/json`. | Yes |
| `Accept` | String | The content 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 |
| :--------- | :--- | :----------------------------------------------------- |
| `disabled` | Bool | Whether the group is banned: `true`: Yes. `false`: No. |
For other fields and descriptions, see [Common parameters](#param).
If the returned HTTP status code is not `200`, the request fails. You can refer to [Status code](#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/XXXX/disable'
```
#### Response example [#response-example-1]
```json
{
"action": "post",
"application": "XXXX",
"applicationName": "XXXX",
"data": {
"disabled": true
},
"duration": 740,
"entities": [],
"organization": "XXXX",
"properties": {},
"timestamp": 1672974260359,
"uri": "http://XXXX/app-id/XXXX/chatgroups/XXXX/disable"
}
```
## Unbanning a group [#unbanning-a-group]
Lifts a ban on the specified group.
After unbanning a group, all group members regain permission to send and receive messages in the group, and the owner and admins regain the privileges necessary to perform supervisory operations.
### HTTP request [#http-request-2]
```html
POST https://{host}/app-id/{app_id}/chatgroups/{group_id}/enable
```
#### Path parameter [#path-parameter-2]
For the descriptions of other path parameters, see [Common Parameters](#param).
#### Request header [#request-header-2]
| Parameter | Type | Description | Required |
| :-------------- | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Content-Type` | String | The content type. Set it as `application/json`. | Yes |
| `Accept` | String | The content 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-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 |
| :--------- | :--- | :----------------------------------------------------- |
| `disabled` | Bool | Whether the group is banned: `true`: Yes. `false`: No. |
For other fields and descriptions, see [Common parameters](#param).
If the returned HTTP status code is not `200`, the request fails. You can refer to [Status code](#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 ' 'http://XXXX/app-id/XXXX/chatgroups/XXXX/enable'
```
#### Response example [#response-example-2]
```json
{
"action": "post",
"application": "XXXX",
"applicationName": "XXXX",
"data": {
"disabled": false
},
"duration": 22,
"entities": [],
"organization": "XXXX",
"properties": {},
"timestamp": 1672974668171,
"uri": "http://XXXX/app-id/XXXX/chatgroups/XXXX/enable"
}
```
## Checking whether a user has joined a group [#checking-whether-a-user-has-joined-a-group]
Checks whether a user has joined a group.
### HTTP request [#http-request-3]
```html
GET https://{host}/app-id/{app_id}/chatgroups/{group_id}/user/{username}/is_joined
```
#### Path parameter [#path-parameter-3]
For the descriptions of path parameters, see [Common Parameters](#param).
#### Request header [#request-header-3]
| Parameter | Type | Description | Required |
| :-------------- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `Accept` | String | The content type. Set it as `application/json`. | Yes |
| `Authorization` | String | The authentication token of the app 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-3]
#### Response body [#response-body-2]
If the returned HTTP status code is `200`, the request succeeds, and the response body contains the following parameters:
| Parameter | Type | Descriptions |
| :-------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------- |
| `data` | Boolean | Whether the user has joined the group: `true`: Yes. The user has joined the group. `false`: No. The user has not joined the group. |
For other fields and descriptions, see [Common parameters](#param).
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
# Replace {YourAppToken} with the app token generated in your server.
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer ' 'https://XXXX/app-id/XXXX/chatgroups/XXXX/user/XXXX/is_joined'
```
#### Response example [#response-example-3]
```json
{
"action": "get",
"application": "8bXXXX02",
"data": false,
"duration": 0,
"organization": "XXXX",
"timestamp": 1691547476492
}
```
## Retrieving group details [#retrieving-group-details]
Retrieves the detailed information of one or more groups. You can retrieve details of up to 100 groups, with each group containing at most 10,000 group members (including the group owner).
If you specify multiple groups, details of the existing groups are returned. If the specified groups do not exist, "group id doesn't exist" is reported.
### HTTP request [#http-request-4]
```bash
GET https://{host}/app-id/{app_id}/chatgroups/{group_ids}
```
#### Path parameter [#path-parameter-4]
| Parameter | Type | Description | Required |
| :---------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `group_ids` | String | The ID of the group whose details you want to retrieve. You can type a maximum of 100 group IDs that are separated with the comma (,). | Yes |
For other parameters and detailed descriptions, see [Common parameters](#param).
#### Request header [#request-header-4]
| 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-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 | Descriptions |
| :------------------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | String | The group ID. The group's unique identifier. |
| `name` | String | The group name. |
| `avatar` | String | The group avatar URL. |
| `description` | String | The group description. |
| `membersonly` | Boolean | Whether a user requesting to join the group requires the approval from the group owner or admin: `true`: Yes. `false`: (Default) No. |
| `allowinvites` | Boolean | Whether a regular group member can invite other users to join the group. `true`: Yes. `false`: No. |
| `maxusers` | Number | The maximum number of members (including the group owner) allowed in the group. |
| `owner` | String | The username of the group owner, for example, `{"owner":"user1"}`. |
| `created` | Long | The Unix timestamp for creating the group. |
| `affiliations_count` | Number | The total number of group members. |
| `disabled` | Bool | Whether the group is banned: `true`: Yes. `false`: No. |
| `affiliations` | Array | The list of existing group members, including the group owner and regular group members, for example, `[{"owner":"user1"},{"member":"user2"},{"member":"user3"}]`. |
| `public` | Boolean | Whether the group is a public group. `true`: Yes. `false`: No. |
| `custom` | String | The extension information of the group. |
| `count` | Number | The number of retrieved groups. |
For other parameters and detailed descriptions, see [Common parameters](#param).
If the returned HTTP status code is not 200, it means the request fails. You can refer to [status code ](#code) for possible causes.
### Example [#example-4]
#### Request example [#request-example-4]
```bash
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer ' 'http://XXXX/app-id/XXXX/chatgroups/66016455491585'
```
#### Response example [#response-example-4]
```json
{
"action": "get",
"application": "09ebbf8b-XXXX-XXXX-bd4b-d47c3b38e434",
"applicationName": "XXXX",
"count": 1,
"data": [
{
"id": "XXXX",
"name": "XXXX",
"avatar": "https://www.XXXX.com/XXX/image",
"description": "XXXX",
"membersonly": true,
"allowinvites": false,
"maxusers": 2000,
"owner": "XXXX",
"created": 1682588716646,
"custom": "",
"mute": false,
"affiliations_count": 2,
"disabled": false,
"affiliations": [
{
"member": "XXXX"
},
{
"owner": "XXXX"
}
],
"public": false
}
"duration": 35,
"entities": [],
"organization": "XXXX",
"properties": {},
"timestamp": 1682588814419,
"uri": "http://XXXX/app-id/XXXX/chatgroups/XXXX"
}
```
## Modifying group information [#modifying-group-information]
Modifies the group information. You can modify the `groupname`, `avatar`, `description`, `maxusers`, `membersonly`, `allowinvites`, `public`, `invite_need_confirm`, and `custom` fields. If you pass in fields that cannot be modified or do not exist in the request, an error is reported.
### HTTP request [#http-request-5]
```bash
PUT https://{host}/app-id/{app_id}/chatgroups/{group_id}
```
#### Path parameter [#path-parameter-5]
| Parameter | Type | Description | Required |
| :--------- | :----- | :------------ | :------- |
| `group_id` | String | The group ID. | Yes |
For other parameters and detailed descriptions, see [Common parameters](#param).
#### 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 ${token}`, 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 |
| :-------------------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `groupname` | String | The group name. It cannot exceed 128 characters. The group name cannot contain "/" or spaces. You can use "+" to represent the space. | Yes |
| `avatar` | String | The group avatar URL. It cannot exceed 1024 characters. | No |
| `description` | String | The group description. It cannot exceed 512 characters. The group name cannot contain "/" or spaces. You can use "+" to represent the space. | Yes |
| `maxusers` | String | The maximum number of group members (including the group owner). The default value is 200 and the maximum value is 2000. The upper limit varies with your price plans. For details, see [Pricing Plan Details](../pricing-plan-details#group). | No |
| `allowinvites` | Boolean | Whether a regular group member can invite other users to join the group. `true`: Yes. `false`: No. Only the group owner or admin can invite other users to join the group. | No |
| `membersonly` | Boolean | Whether the user requesting to join the public group requires approval from the group owner or admin: `true`: Yes. `false`: (Default) No. | No |
| `custom` | String | The extension information of the group. The extension information cannot exceed 1024 characters. | No |
| `invite_need_confirm` | Boolean | Whether the invitee needs to accept the group invitation before joining the group: `true`: Yes. `false`: No. The invitee directly joins the group without confirming the group invitation. | No |
| `public` | Boolean | Whether the group is a public one: `true`: Public group. `false`: Private group. | Yes |
### HTTP response [#http-response-5]
#### Response body [#response-body-4]
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 | Descriptions |
| :------------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------- |
| `groupname` | String | The group name. |
| `description` | String | The group description. |
| `avatar` | Boolean | Whether the group avatar is successfully modified: `true`: Yes. `false`: No. |
| `membersonly` | Boolean | Whether a user requesting to join the group requires the approval from the group owner or admin: `true`: Yes. `false`: (Default) No. |
| `allowinvites` | Boolean | Whether a regular group member can invite other users to join the group. `true`: Yes. `false`: No. |
| `maxusers` | Number | The maximum number of group members (including the group owner). |
For other fields and descriptions, see [Common parameters](#pubparam).
If the returned HTTP status code is not 200, the request fails. You can refer to [Status code ](#code) for possible causes.
### Example [#example-5]
#### Request example [#request-example-5]
```bash
curl -X PUT -H 'Accept: application/json' -H 'Authorization: Bearer ' 'http://XXXX/app-id/XXXX/chatgroups/6XXXX7' -d {
"groupname": "test groupname",
"description": "updategroupinfo12311",
"maxusers": 1500,
"membersonly": true,
"allowinvites": false,
"invite_need_confirm": true,
"custom":"abc",
"public": true
}'
```
#### Response example [#response-example-5]
```json
{
"action": "put",
"application": "XXXXXX",
"applicationName": "XXXX",
"data": {
"allowinvites": true,
"invite_need_confirm": true,
"membersonly": true,
"public": true,
"custom": true,
"description": true,
"maxusers": true,
"groupname": true
"avatar": true
},
"duration": 0,
"entities": [],
"organization": "XXXX",
"properties": {},
"timestamp": 1666062065529,
"uri": "http://XXXX/app-id/XXXX/chatgroups/6XXXX7"
}
```
## Deleting a group [#deleting-a-group]
Deletes the specified group. Once a group is deleted, all the threads in this group are deleted as well.
### HTTP request [#http-request-6]
```bash
DELETE https://{host}/app-id/{app_id}/chatgroups/{group_id}
```
#### Path parameter [#path-parameter-6]
| Parameter | Type | Description | Required |
| :--------- | :----- | :------------ | :------- |
| `group_id` | String | The group ID. | Yes |
For other parameters and detailed descriptions, see [Common parameters](#param).
#### Request header [#request-header-6]
| 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-6]
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 |
| :-------- | :------ | :------------------------------------------------------- |
| `success` | Boolean | The result of this method\:true: Success.false: Failure. |
| `groupid` | String | The group ID to be deleted. |
For other fields and descriptions, see [Common parameters](#param).
If the returned HTTP status code is not 200, the request fails. You can refer to [Status code ](#code) for possible causes.
### Example [#example-6]
#### Request example [#request-example-6]
```bash
curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer ' 'http://XXXX/app-id/XXXX/chatgroups/66021836783617'
```
#### Response example [#response-example-6]
```json
{
"action": "delete",
"application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
"uri": "http://XXXX/app-id/XXXX/chatgroups/66021836783617",
"entities": [],
"data": {
"success": true,
"groupid": "66021836783617"
},
"timestamp": 1542363546590,
"duration": 0,
"organization": "XXXX",
"applicationName": "XXXX"
}
```
## Retrieving all groups [#retrieving-all-groups]
Retrieves all the groups under the app.
### HTTP request [#http-request-7]
```bash
GET https://{host}/app-id/{app_id}/chatgroups
// Gets all groups under the app with pagination
GET https://{host}/app-id/{app_id}/chatgroups?limit={N}&cursor={cursor}
```
#### Path parameter [#path-parameter-7]
For other parameters and detailed descriptions, see [Common parameters](#param).
#### Query parameter [#query-parameter]
| Parameter | Type | Description | Required |
| :-------- | :----- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `limit` | Number | The number of groups to retrieve per page. The default value is `10`. The value range is \[1,1000]. This parameter is required only for paginated queries. | No |
| `cursor` | String | The starting position for data query. This parameter is required only for paginated queries. For the first query, you do not need to set `cursor` and the server returns groups of the number specified with `limit` in the descending order of their creation time. You can get the cursor from the response body and pass it in the URL of the next query request. If there is no longer a `cursor` field in the response body, all groups in the app are retrieved. | No |
If neither the `limit` nor `cursor` parameter is specified, the server returns the latest 10 groups by creation time.
#### Request header [#request-header-7]
| 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-7]
#### Response body [#response-body-5]
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"}`. |
| `groupid` | String | The group ID. |
| `affiliations` | Number | The number of existing group members. |
| `type` | String | The group type. |
| `lastModified` | String | When the group information was last modified, in milliseconds. |
| `groupname` | String | The group name. |
| `count` | Number | The number of groups that are returned. |
| `cursor` | String | The current page number. |
For other fields and descriptions, see [Common parameter](#param).
If the returned HTTP status code is not 200, the request fails. You can refer to [Status code ](#code) for possible causes.
### Example [#example-7]
#### Request example [#request-example-7]
```bash
// Gets the group information of the first page.
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer ' 'http://XXXX/app-id/XXXX/chatgroups?limit=2'
// Gets the group information of the second page.
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer ' 'http://XXXX/app-id/XXXX/chatgroups?limit=2&cursor=ZGNiMjRmNGY1YjczYjlhYTNkYjk1MDY2YmEyNzFmODQ6aW06Z3JvdXA6ZWFzZW1vYi1kZW1vI3Rlc3RhcHA6Mg'
```
#### Response example [#response-example-7]
```json
{
"action": "get",
"params": {
"limit": [
"2"
]
},
"uri": "https://XXXX/app-id/XXXX/chatgroups",
"entities": [],
"data": [
{
"owner": "XXXX#XXXX_user1",
"groupid": "100743775617286960",
"affiliations": 2,
"type": "group",
"lastModified": "1441021038124",
"groupname": "testgroup1"
},
{
"owner": "XXXX#XXXX_user2",
"groupid": "100973270123152176",
"affiliations": 1,
"type": "group",
"lastModified": "1441074471486",
"groupname": "testgroup2"
}
],
"timestamp": 1441094193812,
"duration": 14,
"cursor": "Y2hhdGdyb3VwczplYXNlbW9iLWRlbW8vY2hhdGRlbW91aV8z",
"count": 2
}
```
## Retrieving all the groups a user joins [#retrieving-all-the-groups-a-user-joins]
Retrieves all the groups that a user joins.
### HTTP request [#http-request-8]
```bash
GET https://{host}/app-id/{app_id}/users/{username}/joined_chatgroups?pagesize={}&pagenum={}
```
#### Path parameter [#path-parameter-8]
For the descriptions of path parameters of this method, see [Common parameters](#param).
#### Query parameter [#query-parameter-1]
| Parameter | Type | Description | Required |
| :--------- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| `pagesize` | String | The number of groups to retrieve per page. The value range is \[1,20] and the default value is `5`. If you pass in a value greater than `20`, the server still returns 20 groups. | No |
| `pagenum` | String | The start position for the next query. | No |
#### Request header [#request-header-8]
| 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-8]
#### Response body [#response-body-6]
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 |
| :---------- | :----- | :-------------- |
| `groupid` | String | The group ID. |
| `groupname` | String | The group name. |
For other fields and descriptions, see [Common parameter](#param).
If the returned HTTP status code is not 200, the request fails. You can refer to [status code ](#code) for possible causes.
### Example [#example-8]
#### Request example [#request-example-8]
```bash
curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer ' 'http://XXXX/app-id/XXXX/users/user1/joined_chatgroups?pagesize=100&pagenum=1'
```
#### Response example [#response-example-8]
```json
{
"action":"get",
"application":"8bXXXX02",
"applicationName":"testapp",
"count":0,
"data":[
],
"duration":0,
"entities":[
],
"organization":"XXXX",
"params":
{
"pagesize":
[
"100"
],
"pagenum":
[
"1"
]
},
"properties":{
},
"timestamp":1645177932072,
"uri":"http://XXXX/app-id/XXXX/users/user1/joined_chatgroups"
}
```
## Status codes [#status-codes]
For details, see [HTTP Status Code](../http-status-codes).