POST
/
addsystemcomment

Adding a System Comment

To add a system comment via the API, send a POST request to https://api.velt.dev/addsystemcomment with the following body data.

Body:

{
  data: {
    "apiKey": "your_api_key_here",
    "authToken": "your_token_here",
    "documentId": "your_document_id_here",
    "location": {     // You can pass location object to set a comment to any specific location
      "locationName": "YOUR_LOCATION",
      "version": { //You can optionally set a version in the locatin object // Note: if you set version then id and name fields are mandatory
        "id": "v1",
        "name": "Version 1"
      }
    },
    "targetElement": {
      "elementId": "element_id", // optional (pass elementId if you want to add comment on a specific element)
      "targetText": "target_text", // optional (pass targetText if you want to add comment on a specific text)
      "occurrence": 1, // optional (default: 1) This is relevant for text comment. By default, we will attach comment to the first occurence of the target text in your document. You can change this to attach your comment on a more specific text.
      "selectAllContent": true, // Set to `true` if you want to select all the text content of the target element.
    },
    "status": "open", // optional (default: open)
    "commentData": [ // an array of comment data. Add additional objects of the same schema for each comment reply in the thread.
      {
        "commentText": "This is awesome! Well done.", // To set plain text content
        "commentHtml": "This <span style=\"color: green; background-color: aliceblue; display: inline-block; padding: 4px; border-radius: 4px;\">is test</span> comment.", // To set HTML formatted content
        "replaceContentText": "This is new comment", // provide this replaceContentText to replace current text with
        "replaceContentHtml": "<span>This is <b>new</b> comment.</span>", // If replacement text contains html formatted text, then provide it here
        "from": {
          "email": "user1@domain.com", // required
          "name": "User1" // optional
        }
      }
    ]
  }
}

Not sure where find your Auth Token? You can follow these steps to generate your Auth Token.

selectAllContent

If the selectAllContent field is true then the comment is added to the entire text in the element vs the element itself.

commentHtml

You can pass HTML content here and we will parse this in the comment and also add the html to the target element when the accept button is clicked.

Priority Order of Text to Be Replaced

This is the priority order of the text to be replaced when comment is accepted:

replaceContentHtml > replaceContentText > commentHtml > commentText

Success Response:

{
  "result": {
    "status": "success",
    "message": "System Comment added successfully.",
    "data": {
      "annotationId": "COMMENT_ANNOTATION_ID", // this is the parent comment annotation id.
      "commentIds": [372029, 289088, 910121] // all the child comment ids will be provided in order in this array.
    }
  }
}

Failure Response:

{
  "error": {
    "message": "Auth Token is required.",
    "status": "INVALID_ARGUMENT"
  }
}

Adding a Child System Comment

To add a child system comment, we use the same endpoint for sending system comments, except we also need to add the annotationId field to the body data.

The annotationId field will contain the annotation ID of the parent comment that your child comment will be added to.

{ 
  data: {
    "apiKey": "your_api_key_here",
    "authToken": "your_token_here",
    "documentId": "your_document_id_here",
    "annotationId": "COMMENT_ANNOTATION_ID", // Pass the annotation ID to add a child comment to it.
    "commentData": [ // NOTE: this will be appeneded to the previous comments array
      {
        "commentText": "This is awesome! Well done.", // To set plain text content
        "commentHtml": "This <span style=\"color: green; background-color: aliceblue; display: inline-block; padding: 4px; border-radius: 4px;\">is test</span> comment.", // To set HTML formatted content
        "from": {
          "email": "user1@domain.com", // required
          "name": "User1" // optional
        }
      }
    ]
  }
}
result
object

Response result

status
string

Status for the response

message
string

Status message for the response

data
object

Contains annotationId and commentIds

annotationId
string

This is the parent comment annotation id

commentIds
string[]

An array with all child comment ids

Was this page helpful?