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"
    }
  },
  "signature": "payload_ed25519_hex_signature",
  "source_public_key": "your_client_public_key"
}

Request Attributes

Attribute	Type	Required	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)

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
    },
    "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
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"
}

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
When you query comments, notifications for that room are automatically marked as read for the authenticated person
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)