> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quickblox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List Dialogs
> Retrieve a list of chat dialogs. You can list dialogs using specific search criteria.
#### Recipes
You need to refer to the specific custom object class in the request.
In this case, we refer to the `CoolDialog` custom object class.
See [this section](/reference/create-class) to learn how to create a custom object class.
```curl {3} theme={null}
curl -X GET \
-H "QB-Token: 2e80acd7f3d9c1e79312e0d1dafd6691ba012bba" \
https://api.quickblox.com/chat/Dialog.json?data[class_name]=CoolDialog&data[category]=friends
```
Refer to a specific custom object field in the query.
Here, we refer to the `friends` field of the `CoolDialog` custom object class.
```curl {3} theme={null}
curl -X GET \
-H "QB-Token: 2e80acd7f3d9c1e79312e0d1dafd6691ba012bba" \
https://api.quickblox.com/chat/Dialog.json?data[class_name]=CoolDialog&data[category]=friends
```
```curl theme={null}
curl -X GET \
-H "QB-Token: 2e80acd7f3d9c1e79312e0d1dafd6691ba012bba" \
https://api.quickblox.com/chat/Dialog.json?data[class_name]=CoolDialog&data[category]=friends
```
You can display the total number of all dialogs in the system by setting the `count` to `1`.
```curl {3} theme={null}
curl -X GET\
-H "QB-Token: 1319b4991186601ccf4df2d0fa89565f68012bba" \
https://api.quickblox.com/chat/Dialog.json?count=1
```
```curl theme={null}
curl -X GET\
-H "QB-Token: 1319b4991186601ccf4df2d0fa89565f68012bba" \
https://api.quickblox.com/chat/Dialog.json?count=1
```
You can get a dialog by its ID. Just specify the ID of the dialog in the request.
```curl {3} theme={null}
curl -X GET \
-H "QB-Token: 1319b4991186601ccf4df2d0fa89565f68012bba" \
-d "_id=5d75393ba28f9a17e1cb0f9e" \
https://api.quickblox.com/chat/Dialog.json
```
```curl theme={null}
curl -X GET \
-H "QB-Token: 1319b4991186601ccf4df2d0fa89565f68012bba" \
-d "_id=5d75393ba28f9a17e1cb0f9e" \
https://api.quickblox.com/chat/Dialog.json
```
Use a search operator to perform a query. Here, the `in` operator is applied to a `type` field.
```curl {3} theme={null}
curl -X GET \
-H "QB-Token: 1319b4991186601ccf4df2d0fa89565f68012bba" \
-d "type[in]=1,2&sort_desc=last_message_date_sent&limit=3" \
https://api.quickblox.com/chat/Dialog.json
```
Use a sort operator to order the search results by the field. Here, the `sort_desc` operator is applied to the `last_message_date_sent` field.
```curl {3} theme={null}
curl -X GET \
-H "QB-Token: 1319b4991186601ccf4df2d0fa89565f68012bba" \
-d "type[in]=1,2&sort_desc=last_message_date_sent&limit=3" \
https://api.quickblox.com/chat/Dialog.json
```
You can limit search results on the page using the `limit` parameter.
Here, the number of dialogs on the page is limited to `3`.
```curl {3} theme={null}
curl -X GET \
-H "QB-Token: 1319b4991186601ccf4df2d0fa89565f68012bba" \
-d "type[in]=1,2&sort_desc=last_message_date_sent&limit=3" \
https://api.quickblox.com/chat/Dialog.json
```
The request will return the latest **3** records sorted by the **last\_message\_date\_sent** field in descending order.
```curl theme={null}
curl -X GET \
-H "QB-Token: 1319b4991186601ccf4df2d0fa89565f68012bba" \
-d "type[in]=1,2&sort_desc=last_message_date_sent&limit=3" \
https://api.quickblox.com/chat/Dialog.json
```
```curl {2} theme={null}
curl -X GET \
-H "Authorization: ApiKey 28irlNAGasWDSupO9Vw0BBMZfuHrAUYKpmroS9yBORI" \
-H "On-Behalf-Of: 123" \
https://api.quickblox.com/chat/Dialog.json
```
To execute a request on behalf of a specific user.
```curl {3} theme={null}
curl -X GET \
-H "Authorization: ApiKey 28irlNAGasWDSupO9Vw0BBMZfuHrAUYKpmroS9yBORI" \
-H "On-Behalf-Of: 123" \
https://api.quickblox.com/chat/Dialog.json
```
```curl theme={null}
curl -X GET \
-H "Authorization: ApiKey 28irlNAGasWDSupO9Vw0BBMZfuHrAUYKpmroS9yBORI" \
-H "On-Behalf-Of: 123" \
https://api.quickblox.com/chat/Dialog.json
```
**Search Operators**
The request can contain all, some or none of the next search operators.
| Operator | Description |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| lt | **Less Than** operator
Types: number, string, date
Applicable to fields: last\_message\_date\_sent, created\_at, updated\_at
Example:
?updated\_at\[lt]=1556829805
Will return dialogs with `updated_at` **less than** 1556829805. |
| lte | **Less Than or Equal** to operator
Types: number, string, date
Applicable to fields: last\_message\_date\_sent, created\_at, updated\_at
Example:
?last\_message\_date\_sent\[lte]=1556735709
Will return dialogs with `last_message_date_sent` **less than or equal** 1556735709. |
| gt | **Greater Than** operator
Types: number, string, date
Applicable to fields: last\_message\_date\_sent, created\_at, updated\_at
Example:
?last\_message\_date\_sent\[gt]=1556735709
Will return dialogs with `last_message_date_sent` **greater than** 1556735709. |
| gte | **Greater Than or Equal** to operator
Types: number, string, date
Applicable to fields: last\_message\_date\_sent, created\_at, updated\_at
Example:
?last\_message\_date\_sent\[gt]=1556735709
Will return dialogs with `last_message_date_sent` **greater than** 1556735709. |
| ne | **Not Equal** to operator
Types: number, string, date
Applicable to fields: \_id, name, last\_message\_date\_sent
Example:
?\_id\[ne]=5cc9bb58a28f9a406659d777
Will return dialogs with `_id` **not equal** to 5cc9bb58a28f9a406659d777. |
| in | **Contained IN** array operator
Types: number, string, date
Applicable to fields: type, last\_message\_date\_sent, name
Example:
?type\[in]=1,2
Will return dialogs with type **equal** to 1 and **equal** to 2. |
| nin | **Not contained IN** array operator
Types: number, string, date
Applicable to fields: last\_message\_date\_sent
Example:
?last\_message\_date\_sent\[nin]=1556739654, 1556739987
Will return dialogs with `last_message_date_sent` **not equal** to 1556739654 and 1556739987. |
| all | **ALL contained IN** array
Types: number
Applicable to fields: occupants\_ids, admin\_ids
Example:
?occupants\_ids\[all]=91103344,91142495
Will return dialogs with `occupants_ids` **equal** to 91103344 and 91142495 (both). |
| ctn | **Contains** substring operator
Types: string
Applicable to field: name
Example: ?name\[ctn]=party
Returns dialogs whose name **contains** the word "party". |
**Sort Operators**
Next sorting operators are allowed:
| Operator | Description |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| sort\_asc | Types: all types
Example: sort\_asc=field\_name
Search results will be sorted by the specified field in ascending order. |
| sort\_desc | Types: all types
Example:
sort\_desc=field\_name
Search results will be sorted by the specified field in descending order. |
#### Query Parameters
Search records with the field that contains the specified value. Can be many 1..N.
Filters records with field that contains the value according to the specified value and operator. Can be many 1..N.
Unread message count is calculated for dialogs by default. Set to 0 to skip calculation, which will speed up the request.\
*Added in v2.4.5.*
Limit search results to N records. Useful for pagination.
Skip N records in search results. Useful for pagination.
Count search results. Set to 1 to apply. Response will contain only count of records found. If not passed, the response will contain all available dialog records along with their count.
Search results will be sorted by the specified field in descending order.
Search results will be sorted by the specified field in ascending order.
Class name in Custom Objects.
Field name of class in Custom Objects. Can be many 1..N.
#### Headers
A user or application session token. See [Authentication](/reference/authentication) page to learn more about session tokens. Must be used either QB-Token or Authorization.
API key from Dashboard. Expected format: `ApiKey {your_api_key}`. Must be used either QB-Token or Authorization.
User ID. The user ID of the user on whose behalf the request is being made.
#### Responses
A successful response
```bash cURL theme={null}
curl -X GET \
-H "QB-Token: 1319b4991186601ccf4df2d0fa89565f68012bba" \
https://api.quickblox.com/chat/Dialog.json?limit=2
```
```json 200 theme={null}
{
"total_entries": 6,
"skip": 0,
"limit": 2,
"items": [
{
"_id": "5d75393ba28f9a17e1cb0f9e",
"created_at": "2019-09-08T17:24:11Z",
"last_message": "sure, I can wait",
"last_message_date_sent": 1567971414,
"last_message_id": "5d755856a0eb47411e0b72a9",
"last_message_user_id": 96753878,
"name": "New Year party",
"occupants_ids": [
96753878,
96754523,
96830631,
96831328,
96831397
],
"admin_ids": [],
"photo": "68123",
"type": 2,
"updated_at": "2019-09-08T19:36:54Z",
"user_id": 96753878,
"xmpp_room_jid": "76730_5d75393ba28f9a17e1cb0f9e@muc.chat.quickblox.com",
"unread_messages_count": 0,
"is_join_required": 1
},
{
"_id": "5d753421a28f9a2596cb0f98",
"created_at": "2019-09-08T17:02:26Z",
"last_message": "let's do it at 7pm",
"last_message_date_sent": 1567971391,
"last_message_id": "5d75583fa0eb473c350b72ab",
"last_message_user_id": 96753878,
"name": "Daniel's birthday",
"occupants_ids": [
96753878,
96754523,
96830631,
96831328,
96831397
],
"admin_ids": [],
"photo": "68123",
"type": 2,
"updated_at": "2019-09-08T19:36:31Z",
"user_id": 96753878,
"xmpp_room_jid": "76730_5d753421a28f9a2596cb0f98@muc.chat.quickblox.com",
"unread_messages_count": 0,
"is_join_required": 1
}
]
}
```