Skip to main content

You are viewing Agora Docs forBetaproducts and features. Switch to Docs

Android
iOS
Web
Windows
Unity
Flutter
React Native

Create, delete, and retrieve chat groups

Upon login to the Chat, you can create, modify, or delete a chat 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.

Common parameters

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

Request parameters

ParameterTypeDescriptionRequired
hostStringThe 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.Yes
org_nameStringThe unique identifier assigned to each company (organization) by the Chat service. For how to get the org name, see Get the information of your project.Yes
app_nameStringThe unique identifier assigned to each app by the Chat service. For how to get the app name, see Get the information of your project.Yes
usernameStringThe 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)
  • 26 uppercase English letters (A-Z)
  • 10 numbers (0-9)
  • "_", "-", "."
  • The username is case insensitive, so Aa and aa are the same username.
  • Ensure that each username under the same app is unique.
Yes

Response parameters

ParameterTypeDescription
actionStringThe request method.
organizationStringThe unique identifier assigned to each company (organization) by the Chat service. This is the same as org_name.
applicationStringA unique internal ID assigned to each app by the Chat service. You can safely ignore this parameter.
applicationNameStringThe unique identifier assigned to each app by the Chat service. This is the same as app_name.
uriStringThe request URI.
pathStringThe request path, which is part of the request URI. You can safely ignore this parameter.
entities JSONThe response entity.
dataJSONThe details of the response.
timestampNumberThe Unix timestamp (ms) of the HTTP response.
durationNumberThe duration (ms) from when the HTTP request is sent to the time the response is received.

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:


_1
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.

Creating a group

Creates a new chat group and sets the group information. The group information includes the chat group name, description, whether the group is public or private, the maximum number of chat group members (including the group owner), whether a user requesting to join the group requires approval, the group owner, and group members.

HTTP request


_1
POST https://{host}/{org_name}/{app_name}/chatgroups

Path parameter

For the descriptions of other path parameters, see Common Parameters.

Request header

ParameterTypeDescriptionRequired
Content-TypeStringThe content type. Set it as application/json.Yes
AcceptStringThe content type. Set it as application/json.Yes
AuthorizationStringThe 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

ParameterTypeDescriptionRequired
groupnameStringThe group name. It cannot exceed 128 characters.No
avatarStringThe group avatar URL. It cannot exceed 1024 characters.No
descriptionStringThe group description. It cannot exceed 512 characters.No
publicBooleanWhether 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
maxusersStringThe maximum number of chat 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@agoro.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.No
allowinvitesBooleanWhether a regular group member is allowed to invite other users to join the chat group.
  • true: Yes.
  • false: (Default) No. Only the group owner or admin can invite other users to join the chat 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
membersonlyBooleanWhether 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_confirmBooleanWhether the invitee needs to confirm the received group invitation before joining the group:
  • true: Yes.
  • false: No. The invitee automatically joins the chat group after receiving the group invitation.
No
ownerStringThe chat group owner.Yes
membersArrayThe array of user IDs of chat group members, excluding the group owner. The number of user IDs in the array cannot exceed the value of maxusers.No
customStringThe extension information of the chat group. The extension information cannot exceed 8 KB.No

HTTP response

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.

ParameterTypeDescriptions
groupidStringThe group ID.

For other fields and descriptions, see Common parameters.

If the returned HTTP status code is not 200, the request fails. You can refer to Status code table for possible causes.

Example

Request example


_11
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '{
_11
"groupname": "testgroup",
_11
"avatar": "https://www.XXXX.com/XXX/image",
_11
"description": "test",
_11
"public": true
_11
"maxusers": 300,
_11
"owner": "testuser",
_11
"members": [
_11
"user2"
_11
]
_11
}' 'http://XXXX/XXXX/XXXX/chatgroups'

Response example


_13
{
_13
"action": "post",
_13
"application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
_13
"uri": "http://XXXX/XXXX/XXXX/chatgroups",
_13
"entities": [],
_13
"data": {
_13
"groupid": "6602XXXX783617"
_13
},
_13
"timestamp": 1542361730243,
_13
"duration": 0,
_13
"organization": "XXXX",
_13
"applicationName": "XXXX"
_13
}

Banning a chat group

Bans the specified chat group. Groups are typically banned when too many users or messages violate community guidelines.

Once a chat group is banned, the chat group members in the group can no longer send or receive messages, and the owner and admins cannot perform supervisory operations.

HTTP request


_1
POST https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/disable

Path parameter

For the descriptions of other path parameters, see Common Parameters.

Request header

ParameterTypeDescriptionRequired
Content-TypeStringThe content type. Set it as application/json.Yes
AcceptStringThe content type. Set it as application/json.Yes
AuthorizationStringThe 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

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:

ParameterTypeDescription
disabledBoolWhether the chat group is banned:
  • true: Yes.
  • false: No.
  • For other fields and descriptions, see Common parameters.

    If the returned HTTP status code is not 200, the request fails. You can refer to Status code for possible causes.

    Example

    Request example


    _1
    curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXXX/XXXX/XXXX/chatgroups/XXXX/disable'

    Response example


    _14
    {
    _14
    "action": "post",
    _14
    "application": "XXXX",
    _14
    "applicationName": "XXXX",
    _14
    "data": {
    _14
    "disabled": true
    _14
    },
    _14
    "duration": 740,
    _14
    "entities": [],
    _14
    "organization": "XXXX",
    _14
    "properties": {},
    _14
    "timestamp": 1672974260359,
    _14
    "uri": "http://XXXX/XXXX/XXXX/chatgroups/XXXX/disable"
    _14
    }

    Unbanning a chat group

    Lifts a ban on the specified chat group.

    After unbanning a chat group, all chat 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


    _1
    POST https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/enable

    Path parameter

    For the descriptions of other path parameters, see Common Parameters.

    Request header

    ParameterTypeDescriptionRequired
    Content-TypeStringThe content type. Set it as application/json.Yes
    AcceptStringThe content type. Set it as application/json.Yes
    AuthorizationStringThe 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

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

    ParameterTypeDescription
    disabledBoolWhether the chat group is banned:
  • true: Yes.
  • false: No.
  • For other fields and descriptions, see Common parameters.

    If the returned HTTP status code is not 200, the request fails. You can refer to Status code for possible causes.

    Example

    Request example


    _1
    curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXXX/XXXX/XXXX/chatgroups/XXXX/enable'

    Response example


    _14
    {
    _14
    "action": "post",
    _14
    "application": "XXXX",
    _14
    "applicationName": "XXXX",
    _14
    "data": {
    _14
    "disabled": false
    _14
    },
    _14
    "duration": 22,
    _14
    "entities": [],
    _14
    "organization": "XXXX",
    _14
    "properties": {},
    _14
    "timestamp": 1672974668171,
    _14
    "uri": "http://XXXX/XXXX/XXXX/chatgroups/XXXX/enable"
    _14
    }

    Checking whether a user has joined a group

    Checks whether a user has joined a group.

    HTTP request


    _1
    GET https://{host}/{org_name}/{app_name}/chatgroups/{group_id}/user/{username}/is_joined

    Path parameter

    For the descriptions of path parameters, see Common Parameters.

    Request header

    ParameterTypeDescriptionRequired
    AcceptStringThe content type. Set it as application/json.Yes
    AuthorizationStringThe 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

    Response body

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

    ParameterTypeDescriptions
    dataBooleanWhether 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.

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

    Example

    Request example


    _2
    # Replace {YourAppToken} with the app token generated in your server.
    _2
    curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'https://XXXX/XXXX/XXXX/chatgroups/XXXX/user/XXXX/is_joined'

    Response example


    _8
    {
    _8
    "action": "get",
    _8
    "application": "8bXXXX02",
    _8
    "data": false,
    _8
    "duration": 0,
    _8
    "organization": "XXXX",
    _8
    "timestamp": 1691547476492
    _8
    }

    Retrieving group details

    Retrieves the detailed information of one or more groups. 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


    _1
    GET https://{host}/{org_name}/{app_name}/chatgroups/{group_ids}

    Path parameter

    ParameterTypeDescriptionRequired
    group_idsStringThe 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.

    Request header

    ParameterTypeDescriptionRequired
    AcceptStringThe parameter type. Set it as application/json.Yes
    AuthorizationStringThe 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

    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.

    ParameterTypeDescriptions
    idStringThe group ID. The group's unique identifier.
    nameStringThe group name.
    avatarStringThe group avatar URL.
    descriptionStringThe group description.
    membersonlyBooleanWhether a user requesting to join the group requires the approval from the group owner or admin:
    • true: Yes.
    • false: (Default) No.
    allowinvitesBooleanWhether a regular chat group member can invite other users to join the group.
    • true: Yes.
    • false: No.
    maxusersNumberThe maximum number of members (including the group owner) allowed in the chat group.
    ownerStringThe username of the group owner, for example, {"owner":"user1"}.
    createdLongThe Unix timestamp for creating the chat group.
    affiliations_countNumberThe total number of the chat group members.
    disabledBoolWhether the chat group is banned:
  • true: Yes.
  • false: No.
  • affiliationsArrayThe list of existing group members, including the group owner and regular group members, for example, [{"owner":"user1"},{"member":"user2"},{"member":"user3"}].
    publicBooleanWhether the chat group is a public group.
    • true: Yes.
    • false: No.
    customStringThe extension information of the chat group.
    countNumberThe number of retrieved chat groups.

    For other parameters and detailed descriptions, see Common parameters.

    If the returned HTTP status code is not 200, it means the request fails. You can refer to status code for possible causes.

    Example

    Request example


    _1
    curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXXX/XXXX/XXXX/chatgroups/66016455491585'

    Response example


    _37
    {
    _37
    "action": "get",
    _37
    "application": "09ebbf8b-XXXX-XXXX-bd4b-d47c3b38e434",
    _37
    "applicationName": "XXXX",
    _37
    "count": 1,
    _37
    "data": [
    _37
    {
    _37
    "id": "XXXX",
    _37
    "name": "XXXX",
    _37
    "avatar": "https://www.XXXX.com/XXX/image",
    _37
    "description": "XXXX",
    _37
    "membersonly": true,
    _37
    "allowinvites": false,
    _37
    "maxusers": 2000,
    _37
    "owner": "XXXX",
    _37
    "created": 1682588716646,
    _37
    "custom": "",
    _37
    "mute": false,
    _37
    "affiliations_count": 2,
    _37
    "disabled": false,
    _37
    "affiliations": [
    _37
    {
    _37
    "member": "XXXX"
    _37
    },
    _37
    {
    _37
    "owner": "XXXX"
    _37
    }
    _37
    ],
    _37
    "public": false
    _37
    }
    _37
    "duration": 35,
    _37
    "entities": [],
    _37
    "organization": "XXXX",
    _37
    "properties": {},
    _37
    "timestamp": 1682588814419,
    _37
    "uri": "http://XXXX/XXXX/XXXX/chatgroups/XXXX"
    _37
    }

    Modifying group information

    Modifies the chat 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


    _1
    PUT https://{host}/{org_name}/{app_name}/chatgroups/{group_id}

    Path parameter

    ParameterTypeDescriptionRequired
    group_idStringThe group ID.Yes

    For other parameters and detailed descriptions, see Common parameters.

    Request header

    ParameterTypeDescriptionRequired
    Content-TypeStringThe parameter type. Set it as application/json.Yes
    AcceptStringThe parameter type. Set it as application/json.Yes
    AuthorizationStringThe 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

    ParameterTypeDescriptionRequired
    groupnameStringThe group name. It cannot exceed 128 characters. The group name cannot contain "/" or spaces. You can use "+" to represent the space.Yes
    avatarStringThe group avatar URL. It cannot exceed 1024 characters.No
    descriptionStringThe group description. It cannot exceed 512 characters. The group name cannot contain "/" or spaces. You can use "+" to represent the space.Yes
    maxusersStringThe maximum number of chat 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.No
    allowinvitesBooleanWhether a regular chat 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
    membersonlyBooleanWhether the user requesting to join the public group requires approval from the group owner or admin:
    • true: Yes.
    • false: (Default) No.
    No
    customStringThe extension information of the chat group. The extension information cannot exceed 1024 characters.No
    invite_need_confirmBooleanWhether 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
    publicBooleanWhether the group is a public one:
    • true: Public group.
    • false: Private group.
    Yes

    HTTP response

    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.

    ParameterTypeDescriptions
    groupnameStringThe group name.
    descriptionStringThe group description.
    avatarBooleanWhether the group avatar is successfully modified:
    • true: Yes.
    • false: No.
    membersonlyBooleanWhether a user requesting to join the group requires the approval from the group owner or admin:
    • true: Yes.
    • false: (Default) No.
    allowinvitesBooleanWhether a regular group member can invite other users to join the group.
    • true: Yes.
    • false: No.
    maxusersNumberThe maximum number of chat group members (including the group owner.

    For other fields and descriptions, see Common parameters.

    If the returned HTTP status code is not 200, the request fails. You can refer to Status code for possible causes.

    Example

    Request example


    _10
    curl -X PUT -H 'Accept: application/json' -H 'Authorization: Bearer ' 'http://XXXX/XXXX/XXXX/chatgroups/6XXXX7' -d {
    _10
    "groupname": "test groupname",
    _10
    "description": "updategroupinfo12311",
    _10
    "maxusers": 1500,
    _10
    "membersonly": true,
    _10
    "allowinvites": false,
    _10
    "invite_need_confirm": true,
    _10
    "custom":"abc",
    _10
    "public": true
    _10
    }'

    Response example


    _22
    {
    _22
    "action": "put",
    _22
    "application": "XXXXXX",
    _22
    "applicationName": "XXXX",
    _22
    "data": {
    _22
    "allowinvites": true,
    _22
    "invite_need_confirm": true,
    _22
    "membersonly": true,
    _22
    "public": true,
    _22
    "custom": true,
    _22
    "description": true,
    _22
    "maxusers": true,
    _22
    "groupname": true
    _22
    "avatar": true
    _22
    },
    _22
    "duration": 0,
    _22
    "entities": [],
    _22
    "organization": "XXXX",
    _22
    "properties": {},
    _22
    "timestamp": 1666062065529,
    _22
    "uri": "http://XXXX/XXXX/XXXX/chatgroups/6XXXX7"
    _22
    }

    Deleting a chat group

    Deletes the specified chat group. Once a chat group is deleted, all the threads in this chat group are deleted as well.

    HTTP request


    _1
    DELETE https://{host}/{org_name}/{app_name}/chatgroups/{group_id}

    Path parameter

    ParameterTypeDescriptionRequired
    group_idStringThe group ID.Yes

    For other parameters and detailed descriptions, see Common parameters.

    Request header

    ParameterTypeDescriptionRequired
    AcceptStringThe parameter type. Set it as application/json.Yes
    AuthorizationStringThe 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

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

    ParameterTypeDescription
    successBooleanThe result of this method:
  • true: Success.
  • false: Failure.
  • groupidStringThe group ID to be deleted.

    For other fields and descriptions, see Common parameters.

    If the returned HTTP status code is not 200, the request fails. You can refer to Status code for possible causes.

    Example

    Request example


    _1
    curl -X DELETE -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXXX/XXXX/XXXX/chatgroups/66021836783617'

    Response example


    _14
    {
    _14
    "action": "delete",
    _14
    "application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
    _14
    "uri": "http://XXXX/XXXX/XXXX/chatgroups/66021836783617",
    _14
    "entities": [],
    _14
    "data": {
    _14
    "success": true,
    _14
    "groupid": "66021836783617"
    _14
    },
    _14
    "timestamp": 1542363546590,
    _14
    "duration": 0,
    _14
    "organization": "XXXX",
    _14
    "applicationName": "XXXX"
    _14
    }

    Retrieving all chat groups

    Retrieves all the chat groups under the app.

    HTTP request


    _4
    GET https://{host}/{org_name}/{app_name}/chatgroups
    _4
    _4
    // Gets all groups under the app with pagination
    _4
    GET https://{host}/{org_name}/{app_name}/chatgroups?limit={N}&cursor={cursor}

    Path parameter

    For other parameters and detailed descriptions, see Common parameters.

    Query parameter

    ParameterTypeDescriptionRequired
    limitNumberThe number of chat 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
    cursorStringThe 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 chat 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 chat 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

    ParameterTypeDescriptionRequired
    AcceptStringThe parameter type. Set it as application/json.Yes
    AuthorizationStringThe 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

    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.

    ParameterTypeDescription
    ownerStringThe username of the group owner, for example, {"owner":"user1"}.
    groupidStringThe group ID.
    affiliationsNumberThe number of existing group members.
    typeStringThe group type.
    lastModifiedStringWhen the group information was last modified, in milliseconds.
    groupnameStringThe group name.
    countNumberThe number of groups that are returned.
    cursorStringThe current page number.

    For other fields and descriptions, see Common parameter.

    If the returned HTTP status code is not 200, the request fails. You can refer to Status code for possible causes.

    Example

    Request example


    _5
    // Gets the group information of the first page.
    _5
    curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXXX/XXXX/XXXX/chatgroups?limit=2'
    _5
    _5
    // Gets the group information of the second page.
    _5
    curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXXX/XXXX/XXXX/chatgroups?limit=2&cursor=ZGNiMjRmNGY1YjczYjlhYTNkYjk1MDY2YmEyNzFmODQ6aW06Z3JvdXA6ZWFzZW1vYi1kZW1vI3Rlc3RhcHA6Mg'

    Response example


    _32
    {
    _32
    "action": "get",
    _32
    "params": {
    _32
    "limit": [
    _32
    "2"
    _32
    ]
    _32
    },
    _32
    "uri": "https://XXXX/XXXX/XXXX/chatgroups",
    _32
    "entities": [],
    _32
    "data": [
    _32
    {
    _32
    "owner": "XXXX#XXXX_user1",
    _32
    "groupid": "100743775617286960",
    _32
    "affiliations": 2,
    _32
    "type": "group",
    _32
    "lastModified": "1441021038124",
    _32
    "groupname": "testgroup1"
    _32
    },
    _32
    {
    _32
    "owner": "XXXX#XXXX_user2",
    _32
    "groupid": "100973270123152176",
    _32
    "affiliations": 1,
    _32
    "type": "group",
    _32
    "lastModified": "1441074471486",
    _32
    "groupname": "testgroup2"
    _32
    }
    _32
    ],
    _32
    "timestamp": 1441094193812,
    _32
    "duration": 14,
    _32
    "cursor": "Y2hhdGdyb3VwczplYXNlbW9iLWRlbW8vY2hhdGRlbW91aV8z",
    _32
    "count": 2
    _32
    }

    Retrieving all the chat groups a user joins

    Retrieves all the chat groups that a user joins.

    HTTP request


    _1
    GET https://{host}/{org_name}/{app_name}/user/{username}/joined_chatgroups?pagesize={}&pagenum={}

    Path parameter

    For the descriptions of path parameters of this method, see Common parameters.

    Query parameter

    ParameterTypeDescriptionRequired
    pagesizeStringThe number of chat groups to retrieve per page. The default value is 5. The value range is [1,1000].No
    pagenumStringThe start position for the next query.No
    If neither pagesize nor pagenum is specified, the server returns the top 500 groups in the descending order of when the user joined the groups.

    Request header

    ParameterTypeDescriptionRequired
    AcceptStringThe parameter type. Set it as application/json.Yes
    AuthorizationStringThe 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

    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.

    ParameterTypeDescription
    groupidStringThe group ID.
    groupnameStringThe group name.

    For other fields and descriptions, see Common parameter.

    If the returned HTTP status code is not 200, the request fails. You can refer to status code for possible causes.

    Example

    Request example


    _1
    curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken> ' 'http://XXXX/XXXX/XXXX/users/user1/joined_chatgroups?pagesize=100&pagenum=1'

    Response example


    _27
    {
    _27
    "action":"get",
    _27
    "application":"8bXXXX02",
    _27
    "applicationName":"testapp",
    _27
    "count":0,
    _27
    "data":[
    _27
    ],
    _27
    "duration":0,
    _27
    "entities":[
    _27
    ],
    _27
    "organization":"XXXX",
    _27
    "params":
    _27
    {
    _27
    "pagesize":
    _27
    [
    _27
    "100"
    _27
    ],
    _27
    "pagenum":
    _27
    [
    _27
    "1"
    _27
    ]
    _27
    },
    _27
    "properties":{
    _27
    },
    _27
    "timestamp":1645177932072,
    _27
    "uri":"http://XXXX/XXXX/XXXX/users/user1/joined_chatgroups"
    _27
    }

    Status codes

    For details, see HTTP Status Code.

    vundefined