Develop > Developer reference > Comments API

Comments API

The following APIs are available for use in connection with comments to records:

Add single comment

Enter the following POST request URI:

https://<serverAddress>/rest/<tenant-id>/collaboration/comments/<EntityType>/<EntityId>

where EntityType specifies the record type and EntityId specifies the required record.

An example of a POST request JSON is:

{
	"IsSystem": false,
	"Body": "This is a new comment!",
	"AttachmentIds": [],
	"PrivacyType": "PUBLIC",  //INTERNAL,PUBLIC,AGENTPUBLIC
	"Submitter": {
		"UserId": 10016
	},
	"ActualInterface": "API", //SAW,ESS,EMAIL,API,SYSTEM
	"CommentFrom": "User",   //System,Agent,User,Vendor,ExternalServiceDesk,
        SocialUser
       "CommentTo": "",         //Agent,User,Vendor,ExternalServiceDesk,Stakeholder
	"FunctionalPurpose": "StatusUpdate",  //StatusUpdate,RequestMoreInformation,
        ProvideInformation,EndUserComment,Diagnosis,Resolution,ResolutionActivity,
        FollowUp 
	"Media": "Unknown",     //Unknown,UI,Email,Phone,Fax,InstantMessage,
        InternalChat
	"PersonParticipant": "",
	"CompanyVendor": "",
	"Group": ""
}

The response includes the comment entered in the Body property along with a generated comment ID:

{
    "IsSystem": false,
    "Body": "This is a new comment!",
    "PrivacyType": "PUBLIC",
    "Submitter": {
      "UserId": "10015"
    },
    "ActualInterface": "API",
    "CommentFrom": "User",
    "FunctionalPurpose": "StatusUpdate",
    "Media": "Unknown",
    "PersonParticipant": "",
    "CompanyVendor": "",
    "Group": "",
    "CreateTime": 1452751016929,
    "UpdateTime": 0,
    "Id": "bae223e7-a1e6-4f73-90c3-fd92345c4d7e"
  }

The comment is posted to the specified record.

Add multiple comments

Enter the following POST request URI:

https://<serverAddress>/rest/<tenant-id>/collaboration/comments/bulk/<EntityType>/<EntityId>

where EntityType specifies the record type and EntityId specifies the required record.

A POST request should include an array of JSONs such as this:

{
	"IsSystem": false,
	"Body": "This is a new comment!",
	"AttachmentIds": [],
	"PrivacyType": "PUBLIC",  //INTERNAL,PUBLIC,AGENTPUBLIC
	"Submitter": {
		"UserId": 10016
	},
	"ActualInterface": "API", //SAW,ESS,EMAIL,API,SYSTEM
	"CommentFrom": "User",   //System,Agent,User,Vendor,ExternalServiceDesk,
        SocialUser
       "CommentTo": "",         //Agent,User,Vendor,ExternalServiceDesk,Stakeholder
	"FunctionalPurpose": "StatusUpdate",  //StatusUpdate,RequestMoreInformation,
        ProvideInformation,EndUserComment,Diagnosis,Resolution,ResolutionActivity,
        FollowUp 
	"Media": "Unknown",     //Unknown,UI,Email,Phone,Fax,InstantMessage,
        InternalChat
	"PersonParticipant": "",
	"CompanyVendor": "",
	"Group": ""
}

No data is returned for this request.

The comments are posted to the specified record.

Get comments

Enter the following GET request URI:

https://<serverAddress>/rest/<tenant-id>/collaboration/comments/<EntityType>/<EntityId>

where EntityType specifies the record type and EntityId specifies the required record.

There is an optional parameter PrivacyType, which can be used to specify the comment type. For example, the following request retrieves all public comments:

rest/<tenant>/collaboration/comments/<EntityType>/<EntityId>?PrivacyType=PUBLIC

The response is an array of comments posted to the specified record:

[{
	"IsSystem": false,
	"Body": "This is a new comment2!",
	"AttachmentIds": [],
	"PrivacyType": "PUBLIC",
	"Submitter": {
		"UserId": 10016
	},
	"ActualInterface": "API",
	"CommentFrom": "User",
	"CommentTo": "",
	"FunctionalPurpose": "StatusUpdate",
	"Media": "Unknown",
	"PersonParticipant": "",
	"CompanyVendor": "",
	"Group": ""
},
{
	"IsSystem": false,
	"Body": "This is a new comment3!",
	"AttachmentIds": [],
	"PrivacyType": "PUBLIC",
	"Submitter": {
		"UserId": 10016
	},
	"ActualInterface": "API",
	"CommentFrom": "User",
	"CommentTo": "",
	"FunctionalPurpose": "StatusUpdate",
	"Media": "Unknown",
	"PersonParticipant": "",
	"CompanyVendor": "",
	"Group": ""
},
…
]

Get comments with anonymous agent info

Enter the following GET request URI:

https://<serverAddress>/rest/<tenant-id>/collaboration/comments/<EntityType>/<EntityId>/WithAnonymousAgentInfo

where EntityType specifies the record type and EntityId specifies the required record.

There is an optional parameter PrivacyType, which can be used to specify the comment type.

If the Enable agent anonymity setting is set to On for the tenant and the user running the API does not have login authorization, then when the privacy type is AGENTPUBLIC, the submitter's ID is hidden. A false ID of -9999 is returned instead.

The response is an array of comments posted to the specified record (see the example under Get comments).

Get single comment

Enter the following GET request URI:

https://<serverAddress>/rest/<tenant-id>/collaboration/comments/<EntityType>/<EntityId>/<CommentId>

where EntityType specifies the record type and EntityId specifies the required record. CommentId is the ID of the specific comment.

There are no parameters for this URI.

The response includes the specific comment requested:

{
    "IsSystem": false,
    "Body": "This is a new comment!",
    "PrivacyType": "PUBLIC",
    "Submitter": {
      "UserId": "10016"
    },
    "ActualInterface": "API",
    "CommentFrom": "User",
    "FunctionalPurpose": "StatusUpdate",
    "Media": "Unknown",
    "PersonParticipant": "",
    "CompanyVendor": "",
    "Group": "",
    "CreateTime": 1452749848614,
    "UpdateTime": 0,
    "Id": "92334628-6e8e-46d6-b799-8948e4cd0f89"
  }

Update comment

Enter the following PUT request URI:

https://<serverAddress>/rest/<tenant-id>/collaboration/comments/<EntityType>/<EntityId>/<CommentId>

where EntityType specifies the record type and EntityId specifies the required record.

An example of a PUT request JSON is:

{
	"IsSystem": false,
	"Body": "Updated body!",
	"AttachmentIds": [],
	"PrivacyType": "PUBLIC",    //INTERNAL,PUBLIC,AGENTPUBLIC
	"Submitter": {
		"UserId": 10016
	},
	"ActualInterface": "API",  //SAW,ESS,EMAIL,API,SYSTEM
	"CommentFrom": "User",     //System,Agent,User,Vendor,ExternalServiceDesk,SocialUser
	"CommentTo": "",           //Agent,User,Vendor,ExternalServiceDesk,Stakeholder
	"FunctionalPurpose": "StatusUpdate",  //StatusUpdate,RequestMoreInformation,
        ProvideInformation,EndUserComment,Diagnosis,Resolution,ResolutionActivity,FollowUp 
	"Media": "Unknown",       //Unknown,UI,Email,Phone,Fax,InstantMessage,InternalChat
	"PersonParticipant": "",
	"CompanyVendor": "",
	"Group": "",
	“CreateTime”: 1451360022122,
	“Id”:  “abdec6fb-0bac-4a7b-a533-6735cabf9c88”
}

The response includes the updated comment:

{
    "IsSystem": false,
    "Body": "Updated body!",
    "PrivacyType": "PUBLIC",
    "Submitter": {
      "UserId": "10016"
    },
    "UpdatedBy": {
      "UserId": "10015"
    },
    "ActualInterface": "API",
    "CommentFrom": "User",
    "FunctionalPurpose": "StatusUpdate",
    "Media": "Unknown",
    "PersonParticipant": "",
    "CompanyVendor": "",
    "Group": "",
    "CreateTime": 1452749848614,
    "UpdateTime": 1452751819091,
    "Id": "92334628-6e8e-46d6-b799-8948e4cd0f89"
  }

Note To update existing comments of a record, you must have Comments permission for the relevant record type.

Delete comment

Enter the following DELETE request URI:

https://<serverAddress>/rest/<tenant-id>/collaboration/comments/<EntityType>/<EntityId>/<CommentId>

where EntityType specifies the record type and EntityId specifies the required record.

No data is returned for this request.

Note To delete existing comments of a record, you must have Comments permission for the relevant record type.

Related topics