comments.postComment JS

Skip to end of metadata
Go to start of metadata

Description

 

Posts a comment to a specified comments stream.

Notes: If you are posting a review, please notice the extra required Rating & Reviews related parameters. A review is posted to a comments category that is defined with 'Operation mode: Rating & Reviews'. Learn more in the R&R guide.
We also provide an explanation on how to make the comments in your Comments plugin searchable using Search Engine Optimization (SEO) Support.

 

Note: This method is also supported in our REST API. If you wish to execute this method from your server, please refer to

REST API > comments.postComment.

Syntax

 

Parameters

The following table lists the available parameters:

RequiredNameTypeDescription
categoryIDstringThe identifier of the comments category to which you would like to post the comment.
commentTextstringThe content of the comment to post. The string may be maximum 5000 characters long.
The HTML elements that are allowed are: div, br, p, span - always allowed, and  ul, li, u, b, i, em - allowed when RichText is enabled. Other than these exceptions, the text is sanitized and all other HTML elements are removed.
streamIDstringThe identifier of the comments stream to which you would like to post the comment.
parentIDstringThe identifier of the parent comment. In case this comment is a reply to another comment, this field is the ID of the comment to which this comment replies.
guestNamestringGuest user name. This field is relevant if the user who posted this comment is a guest user, in which case this field is Required.
guestEmailstringGuest user email. This field is relevant if the user who posted this comment is a guest user, in which case this field is Required.
anonymousBooleanIndicates whether to post this comment anonymously. The default value is 'false'.
UIDstringThe unique ID of a logged-in user, with which this method call is associated. This is the UID you receive from Gigya after a successful login of this user. If the user is not a guest (guestName parameter is not defined) this field is Required.
Note: If you are using account linking then the UID would be your site user ID. To learn more about Social Login with account linking (best practice), please refer to the Social Login Implementation guide.
tagsarray

This parameter is a strings array representing a list of tags, e.g.: ["tag_a","tag_b"]. Each tag in the array is assigned to the posted comment. Tags can be used to filter comments when calling comments.getComments, to get only comments that match the tag. The number of tags is restricted to 15 tags per comment.

Note: the tags parameter officially supports alphanumeric characters only. Entering non-alphanumeric characters may cause the method to fail.

cidstring
A string of maximum 100 characters length. The CID sets categories for transactions that can be used later for filtering reports generated by Gigya in the "Context ID" combo box. The CID allows you to associate the report information with your own internal data. For example, to identify a specific widget or page on your site/application. You should not define more than 100 different context IDs.
streamTagsarray or stringEither a comma separated list or a JSON array of tags (strings) that should be associated with the stream. Note: the stream tags will be added to the stream only if this method creates a new stream.
callbackfunction
A reference to a callback function. Gigya calls the specified function along with the results of the API method when the API method completes.
The callback function should be defined with the following signature: functionName(Response).
The "Response Object Data Members" table below provides specification of the data that is passed to the callback function.
contextobject
A developer-created object that is passed back unchanged to the application as one of the fields in the response object.
actionAttributesJSON objectIn Gamification your users receive points for actions they perform on your site, in this case posting a comment grants the user points. Action Attributes may be used to annotate actions with additional information, such as the section of the web site that generated the action. If you set here the actionAttributes, each time a user posts a comment, the action also receives an attribute, for example "tv-show":"glee", which can mean that the action was performed on the "Glee" page of the site. 
actionAttributes contain a JSON object comprised of a series of attribute keys (categories) with associated values. You can also use a generic "tags" key.

No more than three values can be given, they can be with a single key or each have their own key.

For more information see Variants and Action Attributes. Action attributes are later used to filter GM Plugins by a certain attribute.
Example:  {"<attribute key1>": ["<attribute value1>", "<attribute value2>"],  "<attribute key2>": "<attribute value3>" }

 
mediaItemsarrayAn array of URLs of media items to attach to the comment. Currently media items are limited to 3 per comment. If the number of media items exceeds this limit, only the first 3 will be posted. This parameter is only accepted if clientSettings.enableMediaItems is set to true for the category via comments.setCategoryInfo.
taggedUsersarrayAn array of users (UIDs) tagged in the comment body. The taggedUsers array replaces the users that are tagged in the comment. The comment body should have special markup elements that refer to the index of the tagged user in the array. Nulls are allowed members of the array.

Currently tagged users are limited to 10 per comment. If the number of tagged users exceeds this limit, only the first 10 will be posted. This parameter is only accepted if clientSettings.enableUserTagging is set to true for the category via comments.setCategoryInfo.

Rating & Reviews related Parameters:
The following fields are relevant only if you are posting a Review
commentTitlestringThe title for the comment. The title may be maximum 250 characters long.
* This parameter is Required given the following conditions:
  • If you are posting to a categoryID that is defined with 'Operation mode: Rating & Reviews'.
  • And in the Comments Settings of the relevant categoryID, Review title: is set to 'Show' and 'Required'.
  • And the parentID parameter is not specified (i.e., you are posting a Review and not a comment to a review).
   In any other case the commentTitle is irrelevant and is ignored.
ratingsJSON
Object
An object that defines user ratings for this stream.
The object structure is: {'_overall': ratingValue}, where the ratingValue is an integer between 1-5.
* This parameter is Required given the following conditions:
  • If you are posting to a categoryID that is defined with 'Operation mode: Rating & Reviews'.
  • And in the Comments Settings of the relevant categoryID, 'Enable Ratings:' is set to 'Enable'.
  • And the parentID parameter is not specified (i.e. you are posting a Review and not a comment to a review).

   In any other case the ratings is irrelevant and is ignored.

Note: Rating a stream is permitted only for a logged in user who hasn't rated this stream before (each user may rate each stream only once). This method returns an error to a forbidden rating attempt.

Sharing related Parameters:
The following parameters are relevant if you wish to share the comment to social networks
userActionJSON string
or
XML
 
The user action to publish. The UserAction may be represented as a JSON string or XML. Please refer to the UserAction JSON/XML representation.
Notes:
The UserAction JSON/XML is equivalent to the UserAction object in the Web SDK. See further usage details there.
Optional values should be removed from the XML, do not leave empty entries.
See the XML schema at http://socialize.gigya.com/schema/userAction.xsd
UserActionJSON string
or
XML
It is possible to specify different content to publish for each social network. For this purpose, the method supports a set of parameters with the same name format: (i.e. facebook, twitter, yahoo, etc.) followed by "UserAction". For example: twitterUserAction - specifies the content to be used specifically when publishing to Twitter.
Each of these parameters accepts a UserAction JSON/XML (same format as the userAction parameter). Each of these optional parameters if specified overrides the userAction parameter when posting to that provider. In other words, the userAction parameter (see above) specifies the default content to be used for all social networks and UserAction specifies the content to be used for the specific network.
enabledProvidersstring
A comma-delimited list of provider names to include in the method execution. This parameter gives the possibility to apply this method only to a subset of providers of your choice. If you do not set this parameter, by default all the providers are enabled (i.e., the method applies to all connected providers).
For example, if you would like the method to apply only to Twitter, define: enabledProviders: "twitter".
Valid provider names include:
'facebook', 'twitter', 'yahoo''googleplus', 'linkedin'.
disabledProvidersstring
A comma-delimited list of provider names to exclude in the method execution. This parameter gives the possibility to specify providers to which you do not want this method to apply. If you do not set this parameter, by default, no provider is disabled (i.e., the method applies to all connected providers).
For example, if you would like the method to apply to all providers except Twitter, define: disabledProviders: "twitter".
Valid provider names include:
'facebook', 'twitter', 'yahoo''googleplus', 'linkedin'.
shortURLsstring
Using this parameter you may determine whether to use Gigya's URL shortening service for URLs passed in the status parameter. The optional values for this parameter are:
  • 'always' (default): always try to shorten URLs. Where providers permit, URLs are shortened based on the Data Center you are using:
    • fw.to for users of the US data center.
    • shr.gs for users of the European data center.
    • vst.to for users of the Australian data center.
    • socli.ru for users of the Russian data center.
    • s.gigya-api.cn for users of the Chinese data center.
  • 'whenRequired': URLs longer than 139 characters are shortened in accordance with provider preferences.
  • 'never' - never shorten URLs. Where providers permit, URLs are left untouched.

To determine your data center see Finding Your Data Center.


URL shortening requirements vary between providers and depend on the particular type of action and its content. URL shortening is available for the following providers:

ProviderNote
FacebookN/A
TwitterN/A
LinkedInShortened URL is posted to the social network but traffic reports show abbreviated URL (e.g., http://developers.gigya.com/display/GD/showShareBarUI+JS is abbreviated to developers.gigya.com).
MicrosoftNot for share. (Note: messenger has been replaced by microsoft, however, for backward compatibility, either can be used).
DeliciousShortened URL is posted to the social network but traffic reports show abbreviated URL (e.g., http://developers.gigya.com/display/GD/showShareBarUI+JS is abbreviated to developers.gigya.com).
WhatsAppOnly on mobile.
RedditN/A
GooglePlusN/A
Google BookmarksN/A
VKontakteN/A
nk.plN/A
XingN/A
TuentiN/A
HatenaN/A
PinterestShortened URL is posted to the social network but traffic reports show abbreviated URL (e.g., http://developers.gigya.com/display/GD/showShareBarUI+JS is abbreviated to developers.gigya.com).
BaiduN/A
FriendFeedN/A
TumblrN/A
SinaN/A
mixiN/A

When Gigya's URL shortening service is active, Gigya tracks all the traffic coming from the distributed URLs. In such case, 'Referred Traffic' reports will be available to you.

 

 

 

Response Object Data Members

FieldTypeDescription
errorCode integer The result code of the operation. Code '0' indicates success, any other number indicates failure. For a complete list of error codes, see the Response Codes and Errors table.
errorMessage string A short textual description of an error associated with the errorCode for logging purposes.
callId string Unique identifier of the transaction, for debugging purposes.
context object The context object passed by the application as a parameter to the API method, or null if no context object has been passed.
commentComment objectThe posted comment. The comment is returned only if it has been approved.

Events

For a list of possible events triggered when a comment is posted, see Events.

 

Code Sample

var params = {
    categoryID: "12345", 
    streamID:"abc",
    commentText: "I love this!"};

gigya.comments.postComment(params); 

Notes:

  • This sample is not meant to be fully functional code. For brevity's sake, only the code required for demonstrating the API call itself is presented.
  • To run the code on your own domain, add your Gigya API key to the gigya.js URL. A Gigya API key can be obtained on the Site Dashboard page on Gigya's website. Please make sure that the domain from which you are loading the page is the same domain name that you used for generating the API key.
  • In some cases it is necessary to connect/login the user to a provider ? prior to calling the API method. You can learn more in the Social Login guide.