Start a comment thread
Starts a thread on the record, when fieldId is _record, or on one of its fields, with a first comment. The client chooses the thread and comment ids, so that a repeated request finds the thread already present and returns it unchanged. Mentioned users must be able to see the target, and are subscribed to the thread along with the author and the record's creator.
Request
POST https://www.activityinfo.org/resources/form/{formId}/record/{recordId}/comments
Request body
application/json
| object | |||
| threadId | string | The id of the new thread, chosen by the client: a CUID, or any other short alphanumeric id. Repeating a request with the same id returns the existing thread unchanged. | required |
| fieldId | string | The id of the field the thread is about, or `_record` for a thread on the record as a whole. | required |
| commentId | string | The id of the thread's first comment, chosen by the client as the thread id is. | required |
| text | string | The text of the first comment. 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 \
-u anything:APITOKEN \
-H 'Content-type: application/json' \
--data-binary @- << EOF
{
"threadId": "cm2f8xk3v0q1",
"fieldId": "carknkldta8h4o3",
"commentId": "cm2f8xk3v0q2",
"text": "Is this spelled right, @{432202}?",
"mentionIds": [
"432202"
]
}
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": 1,
"lastActivityTime": "1762700000000",
"lastAuthorId": "432201",
"lastCommentPreview": "Is this spelled right, @{432202}?",
"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
}
],
"users": [
{
"id": "432201",
"name": "Alice Example",
"email": "alice@example.org"
},
{
"id": "432202",
"name": "Bob Reviewer",
"email": "bob@example.org"
}
]
}