room_comments:query

Description: Retrieve a list of comments for a specific room.

This endpoint returns all comments in a room, ordered by creation date (newest first). The authenticated person must be a participant in the room or the room creator.

Request Schema

{
  "payload": {
    "type": "room_comments:query",
    "q": {
      "room_id": 123,
      "per_page": 25,
      "page": 1,
      "content_cont": "delivery",
      "mark_as_read": true
    }
  },
  "signature": "payload_ed25519_hex_signature",
  "source_public_key": "your_client_public_key"
}

Request Attributes

Attribute	Type	Required	Default	Description
`q.room_id`	Integer	Yes	-	The ID of the room to retrieve comments from
`q.content_cont`	String	No	-	Records containing a given string in the comment content
`q.person_id_eq`	Integer	No	-	Filter comments by the person who posted them
`q.created_at_gteq`	String	No	-	Filter comments created on or after this date (ISO 8601 format)
`q.created_at_lteq`	String	No	-	Filter comments created on or before this date (ISO 8601 format)
`q.mark_as_read`	Boolean	No	`false`	When `true`, marks room notifications as read for the authenticated person

Authentication Behavior

This endpoint follows Pattern A: Full Account Access.

All authentication methods see the same data - comments are filtered by room participation (person must be a participant or creator of the room).

Response Schema

{
  "source_public_key": "community_public_key",
  "source_site": {
    "protocol": "https",
    "fqdn": "arkipel.localhost:3000"
  },
  "created_at": "2025-03-18T10:30:00Z",
  "signature": "8b6392d5550605bd6ccddf9c21ebec470de4b44e4b4deb746076e37ab61c5346e07e7c7c7cebb5bbee41cdd92a476bcd3f02373d146ec165b31c31fc31c9ce0d",
  "payload": {
    "type": "room_comments:query",
    "q": {
      "per_page": 25,
      "page": 1,
      "total": 15,
      "room_id": 123,
      "mark_as_read": true
    },
    "notifications_marked_as_read": 3,
    "resources": [
      {
        "id": 456,
        "room_id": 123,
        "person": "Jane Smith",
        "person_id": 2,
        "content": "The delivery will arrive at 2 PM today.",
        "content_type": "text/plain",
        "created_at": "2025-03-18T09:30:00Z",
        "updated_at": "2025-03-18T09:30:00Z",
        "commentable": {
          "type": "Distribution",
          "id": 789,
          "name": "Weekly Vegetable Box"
        }
      }
    ]
  }
}

Response Attributes

payload.q - Object - Query metadata including pagination info
- per_page - Integer - Items per page
- page - Integer - Current page number
- total - Integer - Total number of matching comments
- room_id - Integer - The room ID from the query
- mark_as_read - Boolean - The value of the mark_as_read parameter from the request
payload.notifications_marked_as_read - Integer - Number of notifications marked as read (only present when mark_as_read: true)
payload.resources - Array of room comment objects:
- id - Integer - Unique identifier for the comment
- room_id - Integer - ID of the room this comment belongs to
- person - String - Display name of the person who posted the comment
- person_id - Integer - ID of the person who posted the comment
- content - String - The comment content (HTML or plain text)
- content_type - String - Content type (e.g., “text/plain”, “text/html”)
- created_at - ISO 8601 timestamp - When the comment was posted
- updated_at - ISO 8601 timestamp - When the comment was last updated
- commentable - Object - Optional object this comment is about (e.g., Distribution, Item)
  - type - String - Class name of the commented object
  - id - Integer - ID of the commented object
  - name - String - Display name of the commented object

Error Responses

Room Not Found

{
  "source_public_key": "community_public_key",
  "source_site": {
    "protocol": "https",
    "fqdn": "arkipel.localhost:3000"
  },
  "created_at": "2025-03-18T10:30:00Z",
  "signature": "...",
  "payload": {
    "type": "room_comments:query",
    "q": { "room_id": 123 }
  },
  "error": "Room not found with id: 123",
  "status": "not_found"
}

Not a Participant (Forbidden)

{
  "source_public_key": "community_public_key",
  "source_site": {
    "protocol": "https",
    "fqdn": "arkipel.localhost:3000"
  },
  "created_at": "2025-03-18T10:30:00Z",
  "signature": "...",
  "payload": {
    "type": "room_comments:query",
    "q": { "room_id": 123 }
  },
  "error": "Forbidden: You are not a participant in this room",
  "status": "forbidden"
}

Missing Room ID

{
  "source_public_key": "community_public_key",
  "source_site": {
    "protocol": "https",
    "fqdn": "arkipel.localhost:3000"
  },
  "created_at": "2025-03-18T10:30:00Z",
  "signature": "...",
  "payload": {
    "type": "room_comments:query",
    "q": {}
  },
  "error": "Missing required field: room_id",
  "status": "bad_request"
}

Real Life Example

Get comments for a specific room

{
  "payload": {
    "type": "room_comments:query",
    "q": {
      "room_id": 123,
      "per_page": 10,
      "page": 1
    }
  },
  "signature": "...",
  "source_public_key": "your_client_public_key"
}

Search comments by content

{
  "payload": {
    "type": "room_comments:query",
    "q": {
      "room_id": 123,
      "per_page": 20,
      "page": 1,
      "content_cont": "delivery time"
    }
  },
  "signature": "...",
  "source_public_key": "your_client_public_key"
}

Query comments and mark notifications as read

{
  "payload": {
    "type": "room_comments:query",
    "q": {
      "room_id": 123,
      "mark_as_read": true
    }
  },
  "signature": "...",
  "source_public_key": "your_client_public_key"
}

Usage Notes

This is an ephemeral query - no message is persisted to the database
Comments are ordered by created_at DESC (newest first) by default
You must be a participant in the room or the room creator to access comments
Authentication can be via token, whitelist, or membership
The commentable field is only present when the comment is linked to a specific object (like a Distribution)

Marking Notifications as Read

By default, querying comments does not mark notifications as read. To mark notifications as read when querying comments, set mark_as_read: true in the query:

{
  "payload": {
    "type": "room_comments:query",
    "q": {
      "room_id": 123,
      "mark_as_read": true
    }
  }
}

When mark_as_read: true is specified, the response will include notifications_marked_as_read indicating how many notifications were marked as read.