Reply to comment thread

Reply to a comment thread

Adds a comment to an open thread. The client chooses the comment id, so that a repeated request finds the comment already present and returns the thread unchanged. Replying subscribes the author to the thread and marks it unread for the other subscribers.

Request

POST https://www.activityinfo.org/resources/form/{formId}/record/{recordId}/comments/{threadId}/comments

Request body

application/json

object
commentId string The id of the new comment, chosen by the client: a CUID, or any other short alphanumeric id. Repeating a request with the same id returns the thread unchanged. required
text string The comment's text. Mentions are written as `@{userId}` tokens, and each mentioned user id must also be listed in `mentionIds`. required
mentionIds array[string] The ids of the users mentioned in the text, who must be able to see the record. They are subscribed to the thread and notified of it. required

Successful response

application/json

object
thread object The thread itself. required
subscribed boolean True if the user is notified of activity in the thread. required
unread boolean True if the thread has activity the user has not yet seen. required
recordLabel string The record's label as the user sees it, or absent when the thread was listed without labels. optional
comments array[object] The thread's entries in time order, or empty when the thread was listed without its comments. required
users array[object] The authors, subscribers and mentioned users referred to by this view, so that the client can show names without a lookup. required

Error responses

Status Code Error Code Description
400 INVALID_MENTION A mentioned user is not a user of the database or cannot see the record.
400 INVALID_REQUEST The request is malformed: an id is missing or invalid, or the text is empty.
401 AUTHENTICATION_REQUIRED The request must be authenticated
403 FORBIDDEN The user may see the thread but lacks the permission for this operation.
404 NOT_FOUND The form, record, thread or comment does not exist, or the user may not see it.
409 THREAD_ALREADY_OPEN The target already has an open thread; it must be resolved before another is started.
409 THREAD_NOT_RESOLVED The thread is not resolved, so it cannot be reopened.
409 THREAD_RESOLVED The thread is resolved; it can be read and reopened, but not replied to.

Example

curl -X POST https://www.activityinfo.org/resources/form/ck8pu9ha07/record/ck34ujs6v8/comments/cm2f8xk3v0q1/comments \
  -u anything:APITOKEN \
  -H 'Content-type: application/json' \
  --data-binary @- << EOF
{
  "commentId": "cm2f8xk3v0q3",
  "text": "Yes, that is the usual spelling."
}
EOF

The above command returns JSON structured like this:

{
  "thread": {
    "formId": "ck8pu9ha07",
    "recordId": "ck34ujs6v8",
    "fieldId": "carknkldta8h4o3",
    "threadId": "cm2f8xk3v0q1",
    "databaseId": "ck8oykh8m5",
    "startedBy": "432201",
    "startTime": "1762700000000",
    "resolved": false,
    "commentCount": 2,
    "lastActivityTime": "1762703600000",
    "lastAuthorId": "432202",
    "lastCommentPreview": "Yes, that is the usual spelling.",
    "subscriberIds": [
      "432201",
      "432202"
    ]
  },
  "subscribed": true,
  "unread": false,
  "recordLabel": "Anthony Spencer",
  "comments": [
    {
      "formId": "ck8pu9ha07",
      "recordId": "ck34ujs6v8",
      "threadId": "cm2f8xk3v0q1",
      "commentId": "cm2f8xk3v0q2",
      "authorId": "432201",
      "time": "1762700000000",
      "type": "COMMENT",
      "text": "Is this spelled right, @{432202}?",
      "mentionIds": [
        "432202"
      ],
      "deleted": false
    },
    {
      "formId": "ck8pu9ha07",
      "recordId": "ck34ujs6v8",
      "threadId": "cm2f8xk3v0q1",
      "commentId": "cm2f8xk3v0q3",
      "authorId": "432202",
      "time": "1762703600000",
      "type": "COMMENT",
      "text": "Yes, that is the usual spelling.",
      "deleted": false
    }
  ],
  "users": [
    {
      "id": "432201",
      "name": "Alice Example",
      "email": "alice@example.org"
    },
    {
      "id": "432202",
      "name": "Bob Reviewer",
      "email": "bob@example.org"
    }
  ]
}
Next item
Resolve comment thread