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

> Retrieve all chat messages within a particular dialog.

#### Recipes

<AccordionGroup>
  <Accordion title="Filter messages by word">
    <Steps>
      <Step title="1. Set the ID of the dialog">
        Set a `chat_dialog_id` to refer to a specific dialog.

        ```curl {3} theme={null}
        curl -X GET \
        -H "QB-Token: d23b555a6f9b6db4e3ebfd5e02a8e238e5012bba" \
        https://api.quickblox.com/chat/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e&message[ctn]=guys
        ```
      </Step>

      <Step title="2. Set a search operator for a field">
        Apply a search operator to the query. Here, a `ctn` operator is applied to a `message` field with the `guys` value.

        ```curl {3} theme={null}
        curl -X GET \
        -H "QB-Token: d23b555a6f9b6db4e3ebfd5e02a8e238e5012bba" \
        https://api.quickblox.com/chat/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e&message[ctn]=guys
        ```
      </Step>

      <Step title="3. As a result, the API will return messages satisfying the specified criteria.">
        All messages containing the **guys** word are returned for the specified dialog.

        ```curl theme={null}
        curl -X GET \
        -H "QB-Token: d23b555a6f9b6db4e3ebfd5e02a8e238e5012bba" \
        https://api.quickblox.com/chat/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e&message[ctn]=guys
        ```
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Filter and sort messages">
    <Steps>
      <Step title="1. Set the ID of the dialog">
        Set a `chat_dialog_id` to refer to a specific dialog.

        ```curl {3} theme={null}
        curl -X GET \
        -H "QB-Token: d23b555a6f9b6db4e3ebfd5e02a8e238e5012bba" \
        https://api.quickblox.com/chat/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e&date_sent[lt]=1568057349&sort_desc=date_sent
        ```
      </Step>

      <Step title="2. Set a search operator for a field">
        Apply a search operator to the query. Here, the `lt` operator is applied to a `date_sent` field.

        ```curl {3} theme={null}
        curl -X GET \
        -H "QB-Token: d23b555a6f9b6db4e3ebfd5e02a8e238e5012bba" \
        https://api.quickblox.com/chat/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e&date_sent[lt]=1568057349&sort_desc=date_sent
        ```
      </Step>

      <Step title="3. Set a sort operator for a field">
        Use a sort operator to order the search results by the field. Here, the `sort_desc` operator is applied to the `date_sent` field.

        ```curl {3} theme={null}
        curl -X GET \
        -H "QB-Token: d23b555a6f9b6db4e3ebfd5e02a8e238e5012bba" \
        https://api.quickblox.com/chat/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e&date_sent[lt]=1568057349&sort_desc=date_sent
        ```
      </Step>

      <Step title="4. As a result, the API returns messages filtered and sorted upon the request.">
        The messages are returned with the **date\_sent** value less than **1568057349** and are sorted by the **date\_sent** field in **descending** order.

        ```curl theme={null}
        curl -X GET \
        -H "QB-Token: d23b555a6f9b6db4e3ebfd5e02a8e238e5012bba" \
        https://api.quickblox.com/chat/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e&date_sent[lt]=1568057349&sort_desc=date_sent
        ```
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Get message by its ID">
    <Steps>
      <Step title="1. Set the ID of the dialog">
        Set a `chat_dialog_id` to refer to a specific dialog.

        ```curl {3} theme={null}
        curl -X GET \
        -H "QB-Token: d23b555a6f9b6db4e3ebfd5e02a8e238e5012bba" \
        https://api.quickblox.com/chat/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e&_id=5d76a618a28f9a1edfcb0f9b
        ```
      </Step>

      <Step title="2. Set the ID of the message">
        Set an `_id` parameter to refer to a particular message.

        ```curl {3} theme={null}
        curl -X GET \
        -H "QB-Token: d23b555a6f9b6db4e3ebfd5e02a8e238e5012bba" \
        https://api.quickblox.com/chat/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e&_id=5d76a618a28f9a1edfcb0f9b
        ```
      </Step>

      <Step title="3. As a result, the API returns a specified message.">
        ```curl theme={null}
        curl -X GET \
        -H "QB-Token: d23b555a6f9b6db4e3ebfd5e02a8e238e5012bba" \
        https://api.quickblox.com/chat/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e&_id=5d76a618a28f9a1edfcb0f9b
        ```
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Get message by its ID with API key">
    <Steps>
      <Step title="1. Use 'Authorization' header to pass API key">
        ```curl {2} theme={null}
        curl -X GET \
        -H "Authorization: ApiKey 28irlNAGasWDSupO9Vw0BBMZfuHrAUYKpmroS9yBORI" \
        -H "On-Behalf-Of: 123" \
        https://api.quickblox.com/chat/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e&_id=5d76a618a28f9a1edfcb0f9b
        ```
      </Step>

      <Step title="2. Use 'On-Behalf-Of' header to pass user id">
        ```curl {3} theme={null}
        curl -X GET \
        -H "Authorization: ApiKey 28irlNAGasWDSupO9Vw0BBMZfuHrAUYKpmroS9yBORI" \
        -H "On-Behalf-Of: 123" \
        https://api.quickblox.com/chat/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e&_id=5d76a618a28f9a1edfcb0f9b
        ```
      </Step>

      <Step title="3. Set the ID of the dialog">
        Set a `chat_dialog_id` to refer to a specific dialog.

        ```curl {4} theme={null}
        curl -X GET \
        -H "Authorization: ApiKey 28irlNAGasWDSupO9Vw0BBMZfuHrAUYKpmroS9yBORI" \
        -H "On-Behalf-Of: 123" \
        https://api.quickblox.com/chat/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e&_id=5d76a618a28f9a1edfcb0f9b
        ```
      </Step>

      <Step title="4. Set the ID of the message">
        Set an `_id` parameter to refer to a particular message.

        ```curl {4} theme={null}
        curl -X GET \
        -H "Authorization: ApiKey 28irlNAGasWDSupO9Vw0BBMZfuHrAUYKpmroS9yBORI" \
        -H "On-Behalf-Of: 123" \
        https://api.quickblox.com/chat/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e&_id=5d76a618a28f9a1edfcb0f9b
        ```
      </Step>

      <Step title="5. As a result, the API returns a specified message.">
        ```curl theme={null}
        curl -X GET \
        -H "Authorization: ApiKey 28irlNAGasWDSupO9Vw0BBMZfuHrAUYKpmroS9yBORI" \
        -H "On-Behalf-Of: 123" \
        https://api.quickblox.com/chat/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e&_id=5d76a618a28f9a1edfcb0f9b
        ```
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Filter messages by word with API key">
    <Steps>
      <Step title="1. Use 'Authorization' header to pass API key">
        ```curl {2} theme={null}
        curl -X GET \
        -H "Authorization: ApiKey 28irlNAGasWDSupO9Vw0BBMZfuHrAUYKpmroS9yBORI" \
        -H "On-Behalf-Of: 123" \
        https://api.quickblox.com/chat/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e&message[ctn]=guys
        ```
      </Step>

      <Step title="2. Use 'On-Behalf-Of' header to pass user id">
        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/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e&message[ctn]=guys
        ```
      </Step>

      <Step title="3. Set the ID of the dialog">
        Set a `chat_dialog_id` to refer to a specific dialog.

        ```curl {4} theme={null}
        curl -X GET \
        -H "Authorization: ApiKey 28irlNAGasWDSupO9Vw0BBMZfuHrAUYKpmroS9yBORI" \
        -H "On-Behalf-Of: 123" \
        https://api.quickblox.com/chat/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e&message[ctn]=guys
        ```
      </Step>

      <Step title="4. Set a search operator for a field">
        Apply a search operator to the query. Here, a `ctn` operator is applied to a `message` field with the `guys` value.

        ```curl {4} theme={null}
        curl -X GET \
        -H "Authorization: ApiKey 28irlNAGasWDSupO9Vw0BBMZfuHrAUYKpmroS9yBORI" \
        -H "On-Behalf-Of: 123" \
        https://api.quickblox.com/chat/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e&message[ctn]=guys
        ```
      </Step>

      <Step title="5. As a result, the API will return messages satisfying the specified criteria.">
        All messages containing the guys word are returned for the specified dialog.

        ```curl theme={null}
        curl -X GET \
        -H "Authorization: ApiKey 28irlNAGasWDSupO9Vw0BBMZfuHrAUYKpmroS9yBORI" \
        -H "On-Behalf-Of: 123" \
        https://api.quickblox.com/chat/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e&message[ctn]=guys
        ```
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Filter and sort messages with API key">
    <Steps>
      <Step title="1. Use 'Authorization' header to pass API key">
        ```curl {2} theme={null}
        curl -X GET \
        -H "Authorization: ApiKey 28irlNAGasWDSupO9Vw0BBMZfuHrAUYKpmroS9yBORI" \
        -H "On-Behalf-Of: 123" \
        https://api.quickblox.com/chat/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e&date_sent[lt]=1568057349&sort_desc=date_sent
        ```
      </Step>

      <Step title="2. Use 'On-Behalf-Of' header to pass user id">
        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/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e&date_sent[lt]=1568057349&sort_desc=date_sent
        ```
      </Step>

      <Step title="3. Set the ID of the dialog">
        Set a `chat_dialog_id` to refer to a specific dialog.

        ```curl {4} theme={null}
        curl -X GET \
        -H "Authorization: ApiKey 28irlNAGasWDSupO9Vw0BBMZfuHrAUYKpmroS9yBORI" \
        -H "On-Behalf-Of: 123" \
        https://api.quickblox.com/chat/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e&date_sent[lt]=1568057349&sort_desc=date_sent
        ```
      </Step>

      <Step title="4. Set a search operator for a field">
        Apply a search operator to the query. Here, the `lt` operator is applied to a `date_sent` field.

        ```curl {4} theme={null}
        curl -X GET \
        -H "Authorization: ApiKey 28irlNAGasWDSupO9Vw0BBMZfuHrAUYKpmroS9yBORI" \
        -H "On-Behalf-Of: 123" \
        https://api.quickblox.com/chat/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e&date_sent[lt]=1568057349&sort_desc=date_sent
        ```
      </Step>

      <Step title="5. Set a sort operator for a field">
        Use a sort operator to order the search results by the field. Here, the `sort_desc` operator is applied to the `date_sent` field.

        ```curl {4} theme={null}
        curl -X GET \
        -H "Authorization: ApiKey 28irlNAGasWDSupO9Vw0BBMZfuHrAUYKpmroS9yBORI" \
        -H "On-Behalf-Of: 123" \
        https://api.quickblox.com/chat/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e&date_sent[lt]=1568057349&sort_desc=date_sent
        ```
      </Step>

      <Step title="6. As a result, the API returns messages filtered and sorted upon the request.">
        The messages are returned with the **date\_sent** value less than **1568057349** and are sorted by the **date\_sent** field in **descending** order.

        ```curl theme={null}
        curl -X GET \
        -H "Authorization: ApiKey 28irlNAGasWDSupO9Vw0BBMZfuHrAUYKpmroS9yBORI" \
        -H "On-Behalf-Of: 123" \
        https://api.quickblox.com/chat/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e&date_sent[lt]=1568057349&sort_desc=date_sent
        ```
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

All retrieved chat messages will be marked as **read** after request.\
Messages will be marked in 2 cases:

* if the current **user ID** is in `occupants_ids` field for `type=2` (GROUP) dialog;
* if dialog's `type=1` (PUBLIC) dialog.

**Search operators**

The request can contain all, some or none of the next search operators:

| Operator | Description                                                                                                                                                                                                                                                                                                                            |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| lt       | **Less Than** operator  <br />  <br />Types: number, string, date  <br />  <br />Applicable to fields: date\_sent, sender\_id, recipient\_id, updated\_at  <br />  <br />Example:  <br />  <br />date\_sent\[lt]=1556829805  <br />  <br />Description:  <br />  <br />Will return messages with `date_sent` **less than** 1556829805. |
| lte      | **Less Than or Equal** to operator  <br />  <br />Types: number, string, date  <br />  <br />Applicable to fields: date\_sent, sender\_id, recipient\_id, updated\_at  <br />  <br />Example: updated\_at\[lte]=1556829805  <br />  <br />Will return messages with `updated_at` **less than or equal** 1556829805.                    |
| gt       | **Greater Than** operator  <br />  <br />Types: number, string, date  <br />  <br />Applicable to fields: date\_sent, sender\_id, recipient\_id, updated\_at  <br />  <br />Example:  <br />date\_sent\[gt]=1556829805  <br />  <br />Will return messages with `date_sent` **greater than** 1556829805.                               |
| gte      | **Greater Than or Equal** to operator  <br />  <br />Types: number, string, date  <br />  <br />Applicable to fields: date\_sent, sender\_id, recipient\_id, updated\_at  <br />  <br />Example:  <br />date\_sent\[gte]=1556829805  <br />  <br />Will return messages with `date_sent` **greater than or equal** 1556829805.         |
| ne       | **Not Equal** to operator  <br />  <br />Types: number, string, date  <br />  <br />Applicable to fields: \_id, message, date\_sent, sender\_id, recipient\_id  <br />  <br />Example:  <br />recipient\_id\[ne]=9988237  <br />  <br />Will return messages with `recipient_id` **not equal** to 9988237.                             |
| in       | **Contained IN** array operator  <br />  <br />Types: number, string, date  <br />  <br />Applicable to fields: date\_sent, sender\_id, recipient\_id  <br />  <br />Example:  <br />sender\_id\[in]=91419276,91419395  <br />  <br />Will return messages with `sender_id` **equal** to 91419276 and **equal** to 91419395.           |
| nin      | **Not contained IN** array  <br />  <br />Types: number, string, date  <br />  <br />Applicable to fields: date\_sent, sender\_id, recipient\_id  <br />  <br />Example:  <br />recipient\_id\[nin]=91419276,91419395  <br />  <br />Will return messages with `recipient_id` **not equal** to 91419276 and 91419395.                  |
| or       | **OR** operator  <br />  <br />Types: number, string, date  <br />  <br />Applicable to fields: date\_sent, sender\_id, recipient\_id  <br />  <br />Example:  <br />sender\_id\[or]=91419390,96753878  <br />  <br />Will return messages with `sender_id` **equal** to 91419390 **or** 96753878.                                     |
| ctn      | **Contains** substring operator  <br />  <br />Types: string  <br />  <br />Applicable to fields: message  <br />  <br />Example: message\[ctn]=party  <br />  <br />Returns messages which text **contains** the word "party".                                                                                                        |

**Sort operators**

Next sorting operators are allowed:

| Operator   | Description                                                                                                                                                     |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| sort\_asc  | Types: all types  <br />  <br />Example:  <br />sort\_asc=field\_name  <br />  <br />Search results will be sorted by the specified field in ascending order.   |
| sort\_desc | Types: all types  <br />  <br />Example:  <br />sort\_desc=field\_name  <br />  <br />Search results will be sorted by the specified field in descending order. |

#### Query Parameters

<ParamField query="chat_dialog_id" type="string" required> ID of the dialog. </ParamField>
<ParamField query="{message_field_N}" type="string"> Search records with the field that contains the specified value. Can be many 1..N. </ParamField>
<ParamField query="{message_field_N}[{search_operator}]" type="string"> Filters records with field which contains value according to specified value and operator. Can be many 1..N. </ParamField>
<ParamField query="mark_as_read" type="integer"> Mark the requested message as read. Set `mark_as_read=1 `to perform. As a result, when the message is retreived by the opponent, the opponent ID is added to the array of read\_ids field. Works only if the message had the unread status previously, not backwards. You can update message status using the [Update Message](/reference/list-messages#update-message) request. </ParamField>
<ParamField query="limit" type="string" default="100"> Limit search results to N records. Useful for pagination. </ParamField>
<ParamField query="skip" type="string" default="0"> Skip N records in search results. Useful for pagination. </ParamField>
<ParamField query="count" type="string"> Count search results. Response will contain only a count of found records. </ParamField>
<ParamField query="sort_desc" type="string"> Search results will be sorted by a specified field in descending order. </ParamField>
<ParamField query="sort_asc" type="string"> Search results will be sorted by a specified field in ascending order. </ParamField>

#### Headers

<ParamField header="QB-Token" type="string" required> 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. </ParamField>
<ParamField header="Authorization" type="string" default="ApiKey {your_api_key}"> API key from Dashboard. Expected format: `ApiKey {your_api_key}`. Must be used either QB-Token or Authorization.</ParamField>
<ParamField header="On-Behalf-Of" type="string">User ID. The user ID of the user on whose behalf the request is being made.</ParamField>

#### Responses

<AccordionGroup>
  <Accordion title="201">
    A successful response

    <ResponseField name="skip" type="integer" />

    <ResponseField name="limit" type="integer" />

    <ResponseField name="items" type="array of objects">
      <Expandable title="properties">
        <ResponseField name="_id" type="string" />

        <ResponseField name="attachments" type="array">
          <Expandable title="properties">
            <ResponseField name="type" type="string" />

            <ResponseField name="id" type="string" />
          </Expandable>
        </ResponseField>

        <ResponseField name="chat_dialog_id" type="string" />

        <ResponseField name="created_at" type="string" />

        <ResponseField name="date_sent" type="integer" />

        <ResponseField name="delivered_ids" type="array" />

        <ResponseField name="message" type="string" />

        <ResponseField name="read_ids" type="array" />

        <ResponseField name="recipient_id" type="integer" />

        <ResponseField name="sender_id" type="integer" />

        <ResponseField name="updated_at" type="string" />

        <ResponseField name="read" type="integer" />
      </Expandable>
    </ResponseField>
  </Accordion>

  <Accordion title="403">
    An error response

    <ResponseField name="errors" type="array of strings" />
  </Accordion>

  <Accordion title="404">
    An error response

    <ResponseField name="errors" type="array of strings" />
  </Accordion>
</AccordionGroup>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET \
  -H "QB-Token: d23b555a6f9b6db4e3ebfd5e02a8e238e5012bba" \
  https://api.quickblox.com/chat/Message.json?chat_dialog_id=5d75393ba28f9a17e1cb0f9e
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "skip": 0,
    "limit": 100,
    "items": [
      {
        "_id": "5d755856a0eb47411e0b72a9",
        "attachments": [],
        "chat_dialog_id": "5d75393ba28f9a17e1cb0f9e",
        "created_at": "2019-09-08T19:36:54Z",
        "date_sent": 1567971414,
        "delivered_ids": [
          96753878
        ],
        "message": "Hi guys",
        "read_ids": [
          96753878
        ],
        "recipient_id": 0,
        "sender_id": 96753878,
        "updated_at": "2019-09-08T19:36:54Z",
        "read": 0
      },
      {
        "_id": "5d76a618a28f9a1edfcb0f9b",
        "age": "25",
        "attachments": [
          {
            "type": "image",
            "id": "47863"
          },
          {
            "type": "image",
            "id": "47863"
          }
        ],
        "chat_dialog_id": "5d75393ba28f9a17e1cb0f9e",
        "created_at": "2019-09-09T19:20:56Z",
        "date_sent": 1568056856,
        "delivered_ids": [
          96753878
        ],
        "message": "Hi guys!",
        "read_ids": [
          96753878
        ],
        "recipient_id": 343,
        "sender_id": 96753878,
        "updated_at": "2019-09-09T19:20:56Z",
        "read": 0
      }
    ]
  }
  ```

  ```json 403 theme={null}
  {
    "errors": [
      "You don't have appropriate permissions to perform this operation"
    ]
  }
  ```

  ```json 404 theme={null}
  {
    "errors": [
      "The resource wasn't found"
    ]
  }
  ```
</ResponseExample>