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

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.	Yes
`org_name`	String	The 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_name`	String	The 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
`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) 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

Parameter	Type	Description
`action`	String	The request method.
`organization`	String	The unique identifier assigned to each company (organization) by the Chat service. This is the same as `org_name`.
`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. This is the same as `app_name`.
`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

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

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. `false`: 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.

Request parameters ​

Response parameters ​

Request parameters

Response parameters