room_comments:upsert

Description: Create a comment in a room.

Room comments are messages posted within a room by participants. Each comment can optionally be linked to a specific object (e.g., a Distribution, Item) via the commentable field.

---

Request Schema

{
  "payload": {
    "type": "room_comments:upsert",
    "room_id": 123,
    "content": "The vegetables will be ready for pickup tomorrow at 10 AM.",
    "commentable": {
      "type": "Distribution",
      "id": 456
    }
  },
  "signature": "payload_ed25519_hex_signature",
  "source_public_key": "your_client_public_key"
}

Request Attributes

• See global request attributes

Field Constraints

Field	Type	Required	Default	Constraints
room_id	Integer	Yes	null	The ID of the room to post the comment in
content	String	Yes	null	The comment content. Supports HTML or plain text. Required.
commentable	Object	No	null	Optional object this comment is about. See Commentable fields

Commentable Fields

The commentable field links the comment to a specific object (e.g., a Distribution, Item, etc.):

Field	Type	Required	Description
type	String	Yes	Class name of the object: “Distribution”, “Item”, etc.
id	Integer	Yes	ID of the object

Real Life Examples

Simple Text Comment

{
  "type": "room_comments:upsert",
  "room_id": 123,
  "content": "Thanks for the update! I'll be there on time."
}

HTML Content Comment

{
  "type": "room_comments:upsert",
  "room_id": 123,
  "content": "<p>Delivery details:</p><ul><li>Date: March 20</li><li>Time: 10:00 AM</li><li>Location: Community Center</li></ul>"
}

Comment About a Distribution

{
  "type": "room_comments:upsert",
  "room_id": 123,
  "content": "The distribution is delayed by 30 minutes due to traffic.",
  "commentable": {
    "type": "Distribution",
    "id": 456
  }
}

Comment About an Item

{
  "type": "room_comments:upsert",
  "room_id": 123,
  "content": "The tomatoes look great this week!",
  "commentable": {
    "type": "Item",
    "id": 789
  }
}

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": {
    "message_id": "6916452112f746b2b4cf48c1",
    "type": "room_comments:upsert"
  }
}

Response Attributes

• payload.message_id - String - The MongoDB ID of the created message for tracking
• payload.type - String - The message type: “room_comments:upsert”

Error Responses

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:upsert",
    "content": "Test message"
  },
  "error": "Missing required field: room_id must be provided. Please refer to https://devkit.arkipel.co/specs/mutations/room_comments-upsert.html",
  "status": "bad_request"
}

Missing Content

{
  "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:upsert",
    "room_id": 123
  },
  "error": "Missing required field: content must be provided. Please refer to https://devkit.arkipel.co/specs/mutations/room_comments-upsert.html",
  "status": "bad_request"
}

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:upsert",
    "room_id": 99999,
    "content": "Test"
  },
  "error": "Room not found with id: 99999",
  "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:upsert",
    "room_id": 123,
    "content": "Test"
  },
  "error": "Forbidden: You must be a participant in this room to post comments. Only the room creator or existing participants can add comments.",
  "status": "forbidden"
}

---

Usage Notes

• This is a persistent mutation - a message is created and processed asynchronously
• You must be a participant in the room or the room creator to post comments
• Comments support both plain text and HTML content
• When a comment is posted, other participants receive notifications
• The commentable field is optional but useful for linking comments to specific objects
• The authenticated person is automatically set as the comment author
• Comments cannot be edited once posted (this endpoint is for creation only)