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 |
| formId | string | The id of the form of the record the thread is attached to. | required |
| recordId | string | The id of the record the thread is attached to. | required |
| fieldId | string | The id of the field the thread is about, or `_record` for a thread on the record as a whole. | required |
| threadId | string | The id of the thread, unique within the form. | required |
| databaseId | string | The id of the database the form belongs to. | required |
| startedBy | string | The id of the user who started the thread. | required |
| startTime | instant | When the thread was started. | required |
| resolved | boolean | True if the thread has been marked resolved. | required |
| resolvedBy | string | The id of the user who resolved the thread, if it is resolved. | optional |
| resolvedTime | instant | When the thread was resolved, if it is resolved. | optional |
| commentCount | integer | The number of entries in the thread, including resolution events and deleted comments. | required |
| lastActivityTime | instant | The time of the latest entry; threads are listed newest first by this time. | required |
| lastAuthorId | string | The id of the author of the latest entry. | optional |
| lastCommentPreview | string | The first 200 characters of the latest comment, for listing threads without their comments. | optional |
| subscriberIds | array[string] | The ids of the users who are notified of activity in this thread. | 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 |
| formId | string | The id of the form of the record the thread is attached to. | required |
| recordId | string | The id of the record the thread is attached to. | required |
| threadId | string | The id of the thread this entry belongs to. | required |
| commentId | string | The id of this entry, unique within the thread. | required |
| authorId | string | The id of the user who wrote the comment, or who resolved or reopened the thread. | required |
| time | instant | When the entry was made. | required |
| type | string | Whether the entry is a comment, or records the thread being resolved or reopened. Values:
|
required |
| text | string | The comment's text, with mentions written as `@{userId}` tokens. Empty for resolution events and for deleted comments. | required |
| mentionIds | array[string] | The ids of the users mentioned in the text. | required |
| editTime | instant | When the author last edited the text. Absent if the comment was never edited. | optional |
| deleted | boolean | True if the comment was deleted. Its text is then empty, and it stays in the thread as a placeholder. | 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 |
| id | string | The user's id. | required |
| name | string | The user's full name. | required |
| string | The user's email address. | required | |
Error responses
| Status Code | Error Code | Description |
|---|---|---|
| 400 | INVALID_ |
A mentioned user is not a user of the database or cannot see the record. |
| 400 | INVALID_ |
The request is malformed: an id is missing or invalid, or the text is empty. |
| 401 | AUTHENTICATION_ |
The request must be authenticated |
| 403 | FORBIDDEN | The user may see the thread but lacks the permission for this operation. |
| 404 | NOT_ |
The form, record, thread or comment does not exist, or the user may not see it. |
| 409 | THREAD_ |
The target already has an open thread; it must be resolved before another is started. |
| 409 | THREAD_ |
The thread is not resolved, so it cannot be reopened. |
| 409 | THREAD_ |
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"
}
]
}