The Conversations API lets you programmatically retrieve and submit Bazaarvoice Conversations data for use in your applications. To learn more, go to the Conversations API documentation home page.

Contents

(+ show- hide)

Introduction

This tutorial explains how to build feedback submission and display into your applications using the Bazaarvoice Conversations API. Readers will learn how to submit feedback via the Conversations API. The tutorial also addresses the user interface: how to handle syndicated content and also how to simulate 'real time' updating of feedback counts.

Reference documentation on feedback submission is also published on the Developer Portal

Mechanics of submission

This section describes how to submit helpfulness votes and inappropriate feedback. Helpfulness and inappropriate feedback submission follow the same process.

Helpfulness Feedback

Helpfulness Feedback Parameters

The following parameters are needed to submit helpfulness feedback:

Name Description

Header

Content-Type

application/x-www-form-urlencoded

Required This field is required in all API requests.

X-Forwarded-For

IP address of content author

Required This field is required in all API requests.

QueryString

Passkey

Response API passkey.

Required This field is required in all API requests.

Api Version

The latest version of the API.

Required This field is required in all API requests.

FeedbackType

‘helpfulness’

Required This field is required in all API requests.

ContentType

review | question | answer | review_comment

Required This field is required in all API requests.

ContentId

Identification of the content.

Required This field is required in all API requests.

Vote

Positive | Negative. *This parameter is only used when FeedbackType=helpfulness.

Required This field is required in all API requests.

Helpfulness Feedback Request

The sample below represents a helpfulness feedback submission request

POST /data/submitfeedback.json HTTP/1.1
Host: [stg.]api.bazaarvoice.com
X-Forwarded-For: [AuthorIPAddress]
Content-Type: application/x-www-form-urlencoded
...

ApiVersion=[latestApiVersion]&ContentType=[ContentType]&ContentId=[ContentId]&FeedbackType=helpfulness&Vote=[HelpfulnessVote]&PassKey=[yourKey]
This action must be done with an HTTP POST

Inappropriate Feedback

Inappropriate Feedback Parameters

The following parameters are needed to submit inappropriate feedback:

Name Description

Header

Content-Type

application/x-www-form-urlencoded

Required This field is required in all API requests.

X-Forwarded-For

IP address of content author

Required This field is required in all API requests.

QueryString

Passkey

Response API passkey.

Required This field is required in all API requests.

Api Verion

The latest version of the API.

Required This field is required in all API requests.

FeedbackType

‘inappropriate’

Required This field is required in all API requests.

ReasonText

String to identify what is considered inappropriate. *This parameter is only used when FeedbackType=inappropriate. PRR

Optional This field is optional.

ContentType

review | question | answer | review_comment

Required This field is required in all API requests.

ContentId

Identification of the content.

Required This field is required in all API requests.

Inappropriate Feedback Request

The sample below represents an inappropriate feedback submission request

POST /data/submitfeedback.json HTTP/1.1
Host: [stg.]api.bazaarvoice.com
X-Forwarded-For: [AuthorIPAddress]
Content-Type: application/x-www-form-urlencoded
...

ApiVersion=[latestApiVersion]&ContentType=[ContentType]&ContentId=[ContentId]&FeedbackType=inappropriate&PassKey=[yourKey]
This action must be done with an HTTP POST

Handling the response

The sample below represents the response from helpfulness feedback submission.

{
    "Locale": "en_US",
    "Errors": [],
    "Feedback": {
        "Helpfulness": {
            "Vote": "POSITIVE",
            "AuthorId": "zdnjli12ey6odjql8n3zr6arlh"
        }
    },
    "Form": [],
    "FormErrors": {},
    "SubmissionId": null,
    "Data": {},
    "TypicalHoursToPost": null,
    "AuthorSubmissionToken": null,
    "HasErrors": false
}

You will need to look at the response body to determine the status of the request. This is necessary because the Conversations API always returns an HTTP 200 code, even when an error has occurred, in order to support applications using JSONP.

The HasErrors element should be evaluated to determine success/failure of the API. Additional information on possible errors is available here.

Response elements

Name Description
Data

Section containing the fields and field groups.

Locale

The locale that will be associated with this submission.

Errors

This section is populated instead of other fields if there is an error.

Feedback

Object containing the feedback data. This contains the vote value and the author's ID

Form

Section containing an array of field and group references.

FormErrors

Section containing an object whose properties represent user input errors. For example, failure to submit the minimum required characters for a particular field.

SubmissionId

Unique ID assigned to content when submission is successful. This value can be used to look up content later.

Data

Section containing the fields and field groups.

TypicalHoursToPost

Usual time it takes for the content to get posted

AuthorSubmissionToken

HasErrors

Boolean value indicating if there are errors present.

Specific error codes are documented in the feedback reference.

The API response to a feedback submission does not contain the current helpfulness counts. It is up to the implementation to handle tracking the current total until the next display response, which will contain the total. See the Appendix below to read about how to simulate real-time feedback counts.

Feedback User interface

Both feedback counts and feedback controls, buttons or other HTML elements that allow end-users to submit feedback, are commonly found adjacent to the content they are describing. The following image is the recommended user interface layout:

The review title, text, and rating are still the primary featured elements. Feedback counts and feedback controls are secondary. If filtering or sorting on feedback count, consider making the counts more prominent. The feedback counts provide additional context to the content. The feedback controls allow the end-user to weigh in on the content's importance.

Feedback Controls

An end-user must initiate an action to indicate a particular piece of content was note-worthy (helpful or inappropriate). Examples of this include buttons, icons, radio button, or check boxes. Any number of web controls can accomplish this.

Feedback controls may be of type helpfulness or inappropriate. These types are independent of each other. In other words, submitting one type should not disable the other type. The Limiting Users' Feedback section details this concept.

Both these types of feedback controls should only be present for the content pieces that are not syndicated. Syndicated reviews on your site cannot accept feedback. Only native reviews, those reviews collected on your site, can accept feedback. To handle this, clients should base the decision to display HTML feedback controls (such as thumbs-up/thumb-down icons) on the presence/absence of the IsSyndicated key in the review response.

Providing feedback should NOT be enabled for this content. The following is a rule emphasizing this:

  • When IsSyndicated:true do NOT display the option to submit feedback.

  • When IsSyndicated:false, allow end users to provide feedback.

The Syndicated Content tutorial goes into depth about this topic.

Limiting Users Feedback

The Conversations API will not limit a user from submitting feedback more than once. Also, for feedback submission, author's ID is not required. While supporting anonymous submission helps collecting content sentiment, developers will need to limit duplicate submissions in the user interface. Once a type of feedback is provided, the same type of feedback from that end-user should not be accepted.

To limit feedback, we recommend placing flags, such as cookies or local storage, after a user has submitted feedback on a specific piece of content. The existence of the flag can be use to determine if feedback should be allowed. The flag value would need to store the content ID on which feedback was provided. Two flags will be needed, one for helpfulness and one for inappropriate, since they are independent of each other. Feedback HTML controls should be disabled, or hidden, when feedback was already provided. See the sample below:


Clicking on either of the helpfulness votes above does not disable the ability to report content as inappropriate.

How to Simulate 'real-time' Feedback Counts

The Conversations API does not update feedback in real-time. The following techniques can be used to give the impression that feedback is updated in near real-time.

Helpfulness feedback

Feedback counts are part of the standard response from the Conversations API /review endpoint.

In the API response the counts appears as

...
TotalFeedbackCount: 7,
TotalNegativeFeedbackCount: 6,
TotalPositiveFeedbackCount: 1,
...

As previously discussed, these counts are often displayed with the content they represent.

First, an understanding of where helpfulness feedback counts are displayed is needed. This may be not be just on the product display pages, but also on category or other pages. Identifying the locations is needed so that feedback counts are in sync throughout the site.

Once an end user has provided helpfulness feedback the respected count should be adjusted accordingly.

After the helpfulness value updates, end-users should no longer interact with the HTML controls. The buttons below demonstrate this concept.


Click a buttons and refresh the page. The buttons remain disabled and the feedback count remains increased by one. For the purpose of this demo, two flags where set:

  • A flag that captures the new helpfulness count.
  • A flag that represents that the user has submitted a helpfulness vote for a given content ID.

Inappropriate feedback

Inappropriate feedback counts should not be displayed to consumers. If developing an internal application where these counts are need, please contact support.