> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

# QueryMessages

# Package: containersApp

# Namespace: ContainersChat

# Method link: https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-chat/query-messages.md

## Introduction

Retrieves a list of up to 1,000 messages in a conversation, given the provided paging and sorting.

The response includes the in-flight assistant turn when its status is `WORKING`.
To track the assistant's response, poll this method after calling [Send Message](https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-chat/conversation-v1/send-message.md).

Query Messages runs with these defaults, which you can override:
- `createdDate` is sorted in `ASC` order
- `paging.limit` is `50`

To learn about working with Query methods, see [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md), [Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md), and [Field Projection](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-field-projection.md).

---

## REST API

### Schema

```
 Method: queryMessages
 Description: Retrieves a list of up to 1,000 messages in a conversation, given the provided paging and sorting.  The response includes the in-flight assistant turn when its status is `WORKING`. To track the assistant's response, poll this method after calling [Send Message](https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-chat/conversation-v1/send-message.md).  Query Messages runs with these defaults, which you can override: - `createdDate` is sorted in `ASC` order - `paging.limit` is `50`  To learn about working with Query methods, see [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md), [Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md), and [Field Projection](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-field-projection.md).
 URL: https://www.wixapis.com/containers/chat/v1/conversations/{conversationId}/messages/query
 Method: POST
 Method parameters:
   param name: query | type: CursorQuery    
     - name: cursorPaging | type: CursorPaging | description: Cursor token pointing to a page of results. Not used in the first request. Following requests use the cursor token and not `filter` or `sort`.  
        - name: limit | type: integer | description: Maximum number of items to return in the results.  | validation: minimum 0, maximum 100, format int32
        - name: cursor | type: string | description: Pointer to the next or previous page in the list of results.  Pass the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request.  | validation: maxLength 16000
        - name: filter | type: object | description: Filter object in the following format: `"filter" : { "fieldName1": "value1", "fieldName2":{"$operator":"value2"} }` Example of operators: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`, `$hasAll`, `$startsWith`, `$contains`  
        - name: sort | type: array<Sorting> | description: Sort object in the following format: `[{"fieldName":"sortField1","order":"ASC"},{"fieldName":"sortField2","order":"DESC"}]`  | validation: maxItems 5
           - name: fieldName | type: string | description: Name of the field to sort by.  | validation: maxLength 512
           - name: order | type: SortOrder | description: Sort order.  
                 - enum: ASC, DESC
 Return type: QueryMessagesResponse
  - name: messages | type: array<Message> | description: Retrieved messages.  
     - name: id | type: string | description: Message GUID.  | read-only: true | validation: format GUID
     - name: revision | type: string | description: Revision, incremented on each update; used for optimistic concurrency.  | read-only: true | validation: format int64
     - name: createdDate | type: string | description: Date and time the Message was created.  | read-only: true | validation: format date-time
     - name: updatedDate | type: string | description: Date and time the Message was last updated.  | read-only: true | validation: format date-time
     - name: conversationId | type: string | description: GUID of the conversation this Message belongs to. Set on create; immutable afterwards.  | validation: format GUID, immutable
     - name: inReplyToId | type: string | description: For an assistant turn, the GUID of the user Message it answers.  | validation: format GUID
     - name: role | type: Role | description: Who authored the turn (user / assistant / tool).  
         - enum: USER, ASSISTANT, TOOL
     - name: status | type: MessageStatus | description: Lifecycle status of the turn (WORKING -> DONE / ERROR).  
         - enum: WORKING, DONE, ERROR
     - name: parts | type: array<MessagePart> | description: Ordered content parts making up the turn.  | validation: maxItems 200
        - name: type | type: PartType | description: Kind of content carried by this part.  
             - enum: TEXT, CODE, IMAGE, FILE, TOOL_CALL
        - name: text | type: string | description: Inline textual content (used by TEXT / CODE / TOOL_CALL parts).  | validation: maxLength 100000
        - name: uri | type: string | description: Reference to external content (used by IMAGE / FILE parts).  | validation: maxLength 2000
     - name: tasks | type: array<Task> | description: Live work breakdown shown as a checklist on an in-flight assistant turn.  | validation: maxItems 200
        - name: id | type: string | description: Client-supplied task GUID, unique within the turn.  | validation: maxLength 100
        - name: title | type: string | description: Human-readable task description.  | validation: maxLength 500
        - name: status | type: TaskStatus | description: Current status of the task.  
             - enum: PENDING, IN_PROGRESS, DONE_TASK, FAILED
     - name: jobId | type: string | description: GUID of the build job backing this turn, when applicable.  | validation: format GUID
     - name: versionId | type: string | description: Opaque code version produced by an edit turn, when applicable.  | validation: format GUID
     - name: followUpQuestions | type: array<string> | description: Optional suggested next prompts attached to an assistant turn (planning & build). No entity of its own — carried on the message and set on DONE.  | validation: maxItems 50, maxLength 4000
     - name: followUpQuestionOptions | type: array<FollowUpQuestion> | description: Structured follow-up questions with selectable answer options. Superseding follow_up_questions; that field is kept and populated in parallel for callers that have not migrated to this one.  | validation: maxItems 4
        - name: question | type: string | description: The question text.  | validation: maxLength 4000
        - name: options | type: array<string> | description: Selectable answer options for this question.  | validation: maxItems 10, maxLength 200
  - name: pagingMetadata | type: CursorPagingMetadata | description: Paging metadata.  
     - name: count | type: integer | description: Number of items returned in the response.  | validation: format int32
     - name: cursors | type: Cursors | description: Cursor strings that point to the next page, previous page, or both.  
        - name: next | type: string | description: Cursor string pointing to the next page in the list of results.  | validation: maxLength 16000
        - name: prev | type: string | description: Cursor pointing to the previous page in the list of results.  | validation: maxLength 16000
     - name: hasNext | type: boolean | description: Whether there are more pages to retrieve following the current page.  + `true`: Another page of results can be retrieved. + `false`: This is the last page.  


```

### Examples

### Query Messages
Retrieves a list of messages in a conversation.

```curl
curl -X POST \
  'https://www.wixapis.com/containers/chat/v1/conversations/1f5b2c8e-9a3d-4c21-8b77-2d2f6e0a9c10/messages/query' \
  -H 'Authorization: <AUTH>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "cursorPaging": {
        "limit": 50
      }
    }
  }'
```

---

## JavaScript SDK

### Schema

```
 Method: wixClientAdmin.containers.chat.queryMessages(conversationId, options)
 Description: Retrieves a list of up to 1,000 messages in a conversation, given the provided paging and sorting.  The response includes the in-flight assistant turn when its status is `WORKING`. To track the assistant's response, poll this method after calling [Send Message](https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-chat/conversation-v1/send-message.md).  Query Messages runs with these defaults, which you can override: - `createdDate` is sorted in `ASC` order - `paging.limit` is `50`  To learn about working with Query methods, see [API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md), [Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md), and [Field Projection](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-field-projection.md).
 # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present.
 Required parameters:  conversationId
 Method parameters: 
   param name: conversationId | type: string | description: Conversation GUID. | required: true | validation: format GUID
   param name: options | type: QueryMessagesOptions  none  
        - name: query | type: CursorQuery | description: Filtering, sorting, and pagination options.  
           - ONE-OF: 
              - name: cursorPaging | type: CursorPaging | description: Cursor token pointing to a page of results. Not used in the first request. Following requests use the cursor token and not `filter` or `sort`.  
                 - name: limit | type: integer | description: Maximum number of items to return in the results.  | validation: minimum 0, maximum 100, format int32
                 - name: cursor | type: string | description: Pointer to the next or previous page in the list of results.  Pass the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request.  | validation: maxLength 16000
           - name: filter | type: object | description: Filter object in the following format: `"filter" : { "fieldName1": "value1", "fieldName2":{"$operator":"value2"} }` Example of operators: `$eq`, `$ne`, `$lt`, `$lte`, `$gt`, `$gte`, `$in`, `$hasSome`, `$hasAll`, `$startsWith`, `$contains`  
           - name: sort | type: array<Sorting> | description: Sort object in the following format: `[{"fieldName":"sortField1","order":"ASC"},{"fieldName":"sortField2","order":"DESC"}]`  | validation: maxItems 5
              - name: fieldName | type: string | description: Name of the field to sort by.  | validation: maxLength 512
              - name: order | type: SortOrder | description: Sort order.  
                     - enum: ASC, DESC
 Return type: PROMISE<QueryMessagesResponse>
  - name: messages | type: array<Message> | description: Retrieved messages.  
     - name: _id | type: string | description: Message GUID.  | read-only: true | validation: format GUID
     - name: revision | type: string | description: Revision, incremented on each update; used for optimistic concurrency.  | read-only: true | validation: format int64
     - name: _createdDate | type: Date | description: Date and time the Message was created.  | read-only: true 
     - name: _updatedDate | type: Date | description: Date and time the Message was last updated.  | read-only: true 
     - name: conversationId | type: string | description: GUID of the conversation this Message belongs to. Set on create; immutable afterwards.  | validation: format GUID, immutable
     - name: inReplyToId | type: string | description: For an assistant turn, the GUID of the user Message it answers.  | validation: format GUID
     - name: role | type: Role | description: Who authored the turn (user / assistant / tool).  
         - enum: USER, ASSISTANT, TOOL
     - name: status | type: MessageStatus | description: Lifecycle status of the turn (WORKING -> DONE / ERROR).  
         - enum: WORKING, DONE, ERROR
     - name: parts | type: array<MessagePart> | description: Ordered content parts making up the turn.  | validation: maxItems 200
        - name: type | type: PartType | description: Kind of content carried by this part.  
             - enum: TEXT, CODE, IMAGE, FILE, TOOL_CALL
        - name: text | type: string | description: Inline textual content (used by TEXT / CODE / TOOL_CALL parts).  | validation: maxLength 100000
        - name: uri | type: string | description: Reference to external content (used by IMAGE / FILE parts).  | validation: maxLength 2000
     - name: tasks | type: array<Task> | description: Live work breakdown shown as a checklist on an in-flight assistant turn.  | validation: maxItems 200
        - name: _id | type: string | description: Client-supplied task GUID, unique within the turn.  | validation: maxLength 100
        - name: title | type: string | description: Human-readable task description.  | validation: maxLength 500
        - name: status | type: TaskStatus | description: Current status of the task.  
             - enum: PENDING, IN_PROGRESS, DONE_TASK, FAILED
     - name: jobId | type: string | description: GUID of the build job backing this turn, when applicable.  | validation: format GUID
     - name: versionId | type: string | description: Opaque code version produced by an edit turn, when applicable.  | validation: format GUID
     - name: followUpQuestions | type: array<string> | description: Optional suggested next prompts attached to an assistant turn (planning & build). No entity of its own — carried on the message and set on DONE.  | validation: maxItems 50, maxLength 4000
     - name: followUpQuestionOptions | type: array<FollowUpQuestion> | description: Structured follow-up questions with selectable answer options. Superseding follow_up_questions; that field is kept and populated in parallel for callers that have not migrated to this one.  | validation: maxItems 4
        - name: question | type: string | description: The question text.  | validation: maxLength 4000
        - name: options | type: array<string> | description: Selectable answer options for this question.  | validation: maxItems 10, maxLength 200
  - name: pagingMetadata | type: CursorPagingMetadata | description: Paging metadata.  
     - name: count | type: integer | description: Number of items returned in the response.  | validation: format int32
     - name: cursors | type: Cursors | description: Cursor strings that point to the next page, previous page, or both.  
        - name: next | type: string | description: Cursor string pointing to the next page in the list of results.  | validation: maxLength 16000
        - name: prev | type: string | description: Cursor pointing to the previous page in the list of results.  | validation: maxLength 16000
     - name: hasNext | type: boolean | description: Whether there are more pages to retrieve following the current page.  + `true`: Another page of results can be retrieved. + `false`: This is the last page.  


```

### Examples

### Query messages in a conversation
Poll this method after Send Message to track the assistant's response.

```javascript
import { chat } from "@wix/containers";

async function queryMessages() {
  const response = await chat.queryMessages(
    "1f5b2c8e-9a3d-4c21-8b77-2d2f6e0a9c10",
    {
      query: {
        sort: [{ fieldName: "createdDate", order: "ASC" }],
        cursorPaging: { limit: 50 },
      },
    },
  );
}

/* Promise resolves to:
 * {
 *   "messages": [
 *     {
 *       "_id": "d5e9f3c2-1a4b-4c8d-9e7f-2b3c4d5e6f70",
 *       "conversationId": "1f5b2c8e-9a3d-4c21-8b77-2d2f6e0a9c10",
 *       "role": "USER",
 *       "status": "DONE",
 *       "parts": [{ "type": "TEXT", "text": "Add a contact form to the homepage." }],
 *       "revision": 1,
 *       "_createdDate": "2026-07-29T09:02:00.000Z",
 *       "_updatedDate": "2026-07-29T09:02:00.000Z"
 *     },
 *     {
 *       "_id": "f3a7b2c1-8e4d-4f9a-bc12-3d4e5f6a7b8c",
 *       "conversationId": "1f5b2c8e-9a3d-4c21-8b77-2d2f6e0a9c10",
 *       "inReplyToId": "d5e9f3c2-1a4b-4c8d-9e7f-2b3c4d5e6f70",
 *       "role": "ASSISTANT",
 *       "status": "DONE",
 *       "parts": [{ "type": "TEXT", "text": "I've added a contact form to your homepage." }],
 *       "revision": 1,
 *       "_createdDate": "2026-07-29T09:02:05.000Z",
 *       "_updatedDate": "2026-07-29T09:02:30.000Z"
 *     }
 *   ],
 *   "pagingMetadata": {
 *     "count": 2,
 *     "cursors": {},
 *     "hasNext": false
 *   }
 * }
 */

```

### queryMessages (self-hosted)
Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md).

```javascript
import { createClient } from '@wix/sdk';
import { chat } from '@wix/containers';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { chat },
  // Include the auth strategy and host as relevant
});


async function queryMessages(conversationId,options) {
  const response = await myWixClient.chat.queryMessages(conversationId,options);
};
```

---