messages Query

Description

Retrieves a paginated list of messages with optional filtering by order reference and sender type. Results are sorted by timestamp. For marketplace orders, messages may be retrieved from the marketplace system. Page size limits are enforced by the server; you can request a specific page size, and it will be used if it does not exceed the server-enforced maximum. If your requested size exceeds the maximum, the server will enforce the maximum limit. Asking for a conversation marks it read for the current user, so a thread's unreadCount in the messageThreads query drops to zero once it has been opened.

query messages($orderRef: String, $threadKey: ID, $page: Int, $from: FromEnum) {
  messages(
    orderRef: $orderRef
    threadKey: $threadKey
    page: $page
    from: $from
  ) {
    messages {
      _id
      created
      subject
      message
      fromBuyer
      flagged
      archived
      isSystem
      content
      read
      orderId
      orderIncId
      uri
      via
    }
    pagination {
      limit
      count
      page
      pages
      hasMore
    }
  }
}

Variables

{
    "orderRef": "161eabee23cd56d74c488a8d",
    "threadKey": "65beb0fc7e6b1ee0be7263bc",
    "page": 1,
    "from": "buyer"
}

Response

{
    "messages": {
        "messages": [
            {
                "_id": "b72756ed1756c9845cb526c4",
                "created": 1780713945099,
                "subject": "example",
                "message": "example",
                "fromBuyer": true,
                "flagged": true,
                "archived": true,
                "isSystem": true,
                "content": "example",
                "read": true,
                "orderId": "example",
                "orderIncId": 42,
                "uri": "https://www.my-common-ground-store.com/release/1763553751/release-artist-release-name",
                "via": "example"
            }
        ],
        "pagination": {
            "limit": 20,
            "count": 10,
            "page": 1,
            "pages": 1,
            "hasMore": true
        }
    }
}

Arguments

Name	Type	Description
orderRef	String	Order reference ID to filter messages by a specific order.
threadKey	ID	Key of a conversation from the messageThreads query, to read that thread's messages. Ignored when orderRef is given. Use it for threads that have no order — orderRef stays the better argument for the ones that do, since it is what triggers a marketplace sync.
page	Int	The requested page number. Defaults to 1 if not specified.
from	FromEnum	Filter messages by sender type. Use FromEnum enum values.

Returns

MessagesConnection!