# List

## <mark style="color:blue;">GET</mark> api/v1/userChannels/list

* Note: To view a list of group chats.
* Header

| Field         | Type   | Remarks                                                                                |
| ------------- | ------ | -------------------------------------------------------------------------------------- |
| ApiKey        | String | [ApiKey](/relation-one-api/guide/glossary.md#apikey) acquired from the admin           |
| Authorization | String | Bearer ${unifiedAuthToken} , in which the unifiedAuthToken is returned by /api/v1/auth |

* Request Parameters

| Field   | Type   | Remarks                                                                                             |
| ------- | ------ | --------------------------------------------------------------------------------------------------- |
| keyword | String | the name of the group chat. It suppports fuzzy search.                                              |
| limit   | int    | number of records returned by each page                                                             |
| cursor  | String | The cursor data returned by the last page. If cursor is null, then you are querying the first page. |

* Request Example

```shell
curl POST 'https://api.relationlabs.ai/api/v1/userChannels/list?keyword=test&limit=10&cursor=110f37661b2c4fcc9a5186954b3b3da6' \
--header 'ApiKey: <ApiKey>' \
--header 'Authorization: bearer ey1JhbGciOiJFUzI1NiJ9.eyJqdGkiOiI0MzdiN2EzZDEwMGY0ODVkOWVhMW1UzZmZlOWE1NmEyZSIsImlzcyI6InJlbGF0aW9ubGFicy5haSIsImlhdCI6MTY2NTIxNTUzNSwic3ViIjoiZGhreXEtc3FhYWEtYWFhYWotc2d6M3EtY2FpIiwiZXhwIjoxNjY1ODIwMzM1fQ.rj7KKuIcgmvaIwZ63YHnXQ4jvvI-eR2Wo7k3YEyz1Muxo8j5ezCowKDpcW0u9zIuHPFqwD0-1XPWdPLR1d1HLFw'
```

* Response Parameters

| Field | Type                | Remarks            |
| ----- | ------------------- | ------------------ |
| code  | String              | the Return Code    |
| desc  | String              | the Return Message |
| data  | UserChannelResponse | the data           |

The UserChannelResponse field consists of the following subfields:

| Field  | Type                | Remarks                         |
| ------ | ------------------- | ------------------------------- |
| cursor | String              | to query data on the next page. |
| list   | Array\[ChannelInfo] | the list of group chats         |

The ChannelInfo field consists of the following subfields:

| Field              | Type    | Remarks                                                                                                      |
| ------------------ | ------- | ------------------------------------------------------------------------------------------------------------ |
| status             | String  | the status of the group chat: 0-normal; 1-left; 2-removed by the admin; 3-the group chat had been dismissed. |
| channelUuid        | String  | the uuid of the group chat                                                                                   |
| displayName        | String  | the name of the group chat                                                                                   |
| channelIcon        | String  | the icon of the group chat                                                                                   |
| channelType        | String  | the type of the group chat                                                                                   |
| unreadMessageCount | String  | counts of messages unread                                                                                    |
| mentionsCount      | String  | how many mentions                                                                                            |
| lastMessageType    | String  | the type of the last message: TEXT\SYS\CARD                                                                  |
| lastMessageContent | String  | the content of the last message                                                                              |
| lastPostAt         | Long    | the timestamp of the last message                                                                            |
| mute               | boolean | Whether to mute it. True-yes, False-no.                                                                      |
| pin                | boolean | Whether it should be sticked on top. True-yes，False-no.                                                      |

* Response Body

```json
{
    "code": "0",
    "desc": "success",
    "data": {
        "cursor": "bbaac023563e4c399228eb6763034965",
        "list": [
            {
                "status": 0,
                "channelUuid": "e54d938caa09498fa1a09f7cfe4e21f4",
                "displayName": "test-group",
                "channelIcon": "",
                "channelType": "G",
                "unreadMessageCount": 0,
                "mentionsCount": 0,
                "lastMessageType": "SYS",
                "lastMessageContent": "0x1e56 created Group test-group",
                "lastPostAt": "1665219499000",
                "mute": true,
                "pin": true
            },
            ...
        ]
    }
}
```

* Return Code

| code  | desc             | Remarks                           |
| ----- | ---------------- | --------------------------------- |
| 0     | success          | the flag for a successful request |
| 13101 | group type error | cannot recognize the group type   |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://relationlabs.gitbook.io/relation-one-api/api/chats/list.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.