Documentation
Chat (BETA)
Console 官网 Community Technical support
English
search-icon

Create, Delete, and Retrieve Chat Groups

Last updated 2022/08/23 02:07:11

Upon login to the Agora Chat, you can create, modify, or delete a chat group.

This page shows how to create, retrieve, modify, and delete a group by calling Agora 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 Agora Chat RESTful APIs:

Request parameters

Parameter Type Description Required
host String The domain name assigned by the Agora Chat service to access RESTful APIs. For how to get the domain name, see Get the information of your project. Yes
org_name String The unique identifier assigned to each company (organization) by the Agora Chat service. For how to get the org name, see Get the information of your project. Yes
app_name String The unique identifier assigned to each app by the Agora Chat service. For how to get the app name, see Get the information of your project. Yes
username String The username. The unique login account of the user. The username 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 must be unique.
    		 Yes

    Response parameters

    Parameter Type Description
    action String The request method.
    organization String The unique identifier assigned to each company (organization) by the Agora Chat service. This is the same as org_name.
    application String A unique internal ID assigned to each app by the Agora Chat service. You can safely ignore this parameter.
    applicationName String The unique identifier assigned to each app by the Agora Chat service. This is the same as app_name.
    uri String The request URI.
    path String The request path, which is part of the request URL. 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

    Agora 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:

    Authorization: Bearer ${YourAppToken}

    In order to improve the security of the project, Agora uses a token (dynamic key) to authenticate users before they log into the chat system. The Agora Chat RESTful API only supports 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

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

    Path parameter

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

    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

    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
    desc String The group description. It cannot exceed 512 characters. The group name cannot contain "/" or spaces. You can use "+" to represent the space. Yes
    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
    		 Yes
    maxusers String The 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
    allowinvites Boolean Whether 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
    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
    owner String The chat group owner. Yes
    members Array Regular chat group members. This chat group member array does not contain the group owner. If you want to set this field, you can enter one to 100 elements in this array. No
    custom String The 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.

    Parameter Type Descriptions
    groupid String The group ID.

    For other fields and descriptions, see Public parameter.

    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

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

    Response example

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

    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

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

    Path parameter

    Parameter Type Description Required
    group_ids String The 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

    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

    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
    id String The group ID. The group's unique identifer.
    name String The group name.
    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 chat 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 chat group.
    owner String The username of the group owner, for example, {"owner":"user1"}.
    created Long The Unix timestamp for creating the chat group.
    affiliations_count Number The total number of the chat group members.
    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 chat group is a public group.
    • true: Yes.
    • fale: No.
    custom String The 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

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

    Response example

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

    Modifying group information

    Modifies the chat group information. You can only modify the groupname, desc, maxusers, membersonly, allowinvites, 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

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

    Path parameter

    Parameter Type Description Required
    group_id String The group ID. Yes

    For other parameters and detailed descriptions, see Common parameters.

    Request header

    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

    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
    desc 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 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
    allowinvites Boolean Whether a regular chat group membercan 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 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.

    Parameter Type Descriptions
    groupname String The group name.
    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 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

    curl -X PUT -H 'Content-Type: application/json' -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' -d '{
    "groupname": "testgroup1",
    "description": "test",
    "maxusers": 300,
    "membersonly": true,
    "allowinvites": true
}' 'http://XXXX/XXXX/XXXX/chatgroups/66021836783617'

    Response example

    {
    "action": "put",
    "application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
    "uri": "http://XXXX/XXXX/XXXX/chatgroups/66021836783617",
    "entities": [],
    "data": {
      "membersonly": true,
      "allowinvites": true,
      "description": true,
      "maxusers": true,
      "groupname": true
    },
    "timestamp": 1542363146301,
    "duration": 0,
    "organization": "XXXX",
    "applicationName": "XXXX"
}

    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

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

    Path parameter

    Parameter Type Description Required
    group_id String The group ID. Yes

    For other parameters and detailed descriptions, see Common parameters.

    Request header

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

    HTTP response

    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.

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

    Example

    Request example

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

    Response example

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

    Retrieving all chat groups

    Retrieves all the chat groups under the app.

    HTTP request

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

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

    Path parameter

    For other parameters and detailed descriptions, see Common parameters.

    Request header

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

    Request body

    Parameter Type Description Required
    limit String The number of groups obtained at one go. No
    cursor String The current page number. This parameter is required if you want to get group details with pagination. This parameter specifies where you want to start querying from. 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.

    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.
    last_modified 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 Public 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

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

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

    Response example

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

    Retrieving all the chat groups a user joins

    Retrieves all the chat groups that a user joins.

    HTTP request

    GET https://{host}/{org_name}/{app_name}/users/{username}/joined_chatgroups

    Path parameter

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

    Request header

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

    HTTP response

    Response body

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

    Parameter Type Description
    groupid String The group ID.
    groupname String The group name.

    For other fields and descriptions, see Public 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

    curl -X GET -H 'Accept: application/json' -H 'Authorization: Bearer <YourAppToken>' 'http://XXXX/XXXX/XXXX/users/user1/joined_chatgroups'

    Response example

    {
    "action": "get",
    "application": "8be024f0-XXXX-XXXX-b697-5d598d5f8402",
    "uri": "http://XXXX/XXXX/XXXX/users/user1/joined_chatgroups",
    "entities": [],
    "data": [
      {
        "groupid": "66016455491585",
        "groupname": "testgroup1"
      },
      {
        "groupid": "66016467025921",
        "groupname": "testgroup2"
      },
    ],
    "timestamp": 1542359565885,
    "duration": 1,
    "organization": "XXXX",
    "applicationName": "XXXX",
    "count": 2
}

    Status codes

    For details, see HTTP Status Codes.