Skip to main content

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. The group name cannot contain "/" or spaces. You can use "+" to represent the space.Yes
descStringThe group description. It cannot exceed 512 characters. The group name cannot contain "/" or spaces. You can use "+" to represent the space.Yes
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
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 group member is allowed to invite other users to join the chat group.
  • true: Yes.
  • false: No. Only the group owner or admin can invite other users to join the chat 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
ownerStringThe chat group owner.Yes
membersArrayRegular chat group members. This chat group member array does not contain the group owner. If you want to set this field, you can enter 1 to 100 elements in this array.No
customStringThe extension information of the chat group. The extension information cannot exceed 1024 characters.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


_10
curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '{
_10
"groupname": "testgroup",
_10
"desc": "test",
_10
"public": true
_10
"maxusers": 300,
_10
"owner": "testuser",
_10
"members": [
_10
"user2"
_10
]
_10
}' '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
    }

    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 one or more 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.
    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.

    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": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
    _37
    "uri": "http://XXXX/XXXX/XXXX/chatgroups/66016455491585",
    _37
    "entities": [],
    _37
    "data": [
    _37
    {
    _37
    "id": "66016455491585",
    _37
    "name": "testgroup1",
    _37
    "description": "testgroup1",
    _37
    "membersonly": false,
    _37
    "allowinvites": false,
    _37
    "maxusers": 200,
    _37
    "owner": "user1",
    _37
    "created": 1542356598609,
    _37
    "custom": "",
    _37
    "affiliations_count": 3,
    _37
    "disable":false,
    _37
    "affiliations": [
    _37
    {
    _37
    "member": "user3"
    _37
    },
    _37
    {
    _37
    "member": "user2"
    _37
    },
    _37
    {
    _37
    "owner": "user1"
    _37
    }
    _37
    ],
    _37
    "public": true
    _37
    }
    _37
    ],
    _37
    "timestamp": 1542360200677,
    _37
    "duration": 0,
    _37
    "organization": "XXXX",
    _37
    "applicationName": "XXXX",
    _37
    }

    Modifying group information

    Modifies the chat group information. You can modify the groupname, 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
    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.
    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


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

    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,100].No
    cursorStringThe start position for the next query.No
    If the limit and cursor parameters are not specified, the basic information of 10 chat groups on the first page is returned by default.

    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.
    last_modifiedStringWhen 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
    "last_modified": "1441021038124",
    _32
    "groupname": "testgroup1"
    _32
    },
    _32
    {
    _32
    "owner": "XXXX#XXXX_user2",
    _32
    "groupid": "100973270123152176",
    _32
    "affiliations": 1,
    _32
    "type": "group",
    _32
    "last_modified": "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}/{app_name}/users/{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 10. The value range is [1,100].No
    pagenumStringThe start position for the next query.No
    If the pagesize and pagenum parameters are not specified, the basic information of 10 chat groups on the first page is returned by default.

    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=1&pagenum=100'

    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
    "1"
    _27
    ],
    _27
    "pagenum":
    _27
    [
    _27
    "100"
    _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.