Conversations API: Retrieve and submit consumer-generated content (CGC), and retrieve your product catalog and statistics about your CGC.
Platform & API Concepts
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.
This page explains important concepts that you need to know in order to use the Conversations Platform and API.
Anatomy of an API request
All requests to the Conversations API will include the following components:
The Conversations API supports both http and https. We recommend using https for all requests. See Secure requests below for more information.
This token will be replaced with
Our CDN uses this section to route requests to the Conversations API application servers.
Used to identify which content type you would like to request or submit. Learn more at Display Fundamentals and Submission Fundamentals.
The Conversations API currently supports both JSON and XML.
Identifies which version of the API will process your request. You should always use the latest version. Continue to Versioning below to learn more.
API keys are used to identify which client's data should be returned and are used for tracking and metrics. To learn how to get API keys read Key request process.
When a secure request is made using the HTTPS protocol, the following assets are returned with a secure scheme:
- Bazaarvoice-hosted photos
- Bazaarvoice-hosted syndication attribution values
- YouTube URLs
Other assets, like those imported into the Bazaarvoice platform via a product feed, are not altered when a secure request is made. For example, product image URLs using HTTP, provided to Bazaarvoice using a feed, will not be upgraded to HTTPS.
The Conversations API supports the following environments:
Used while developing your application. Content submitted to this environment will be automatically published approximately every 15 minutes. Staging is virtually identical to production in implementation, but not scale. Please do not attempt load testing in staging.
Used when your application is complete. Content submitted to this environment will be manually moderated in 72 business hours or less. Please contact us if you would like to do automated performance testing, such as load testing or security scans, against production.
The Bazaarvoice Conversations API is versioned so that we can release new features, bug fixes and improvements without compromising the stability of applications using the API.
This table shows all Conversations API versions.
|Version||Release Date||Deprecation Date||Status|
|Beta (PRR)||Invite only||August 2011||Deprecated|
|4.9 (PRR)||August 2011||April 30th, 2016||Deprecated|
|5.0 (PRR)||October 2011||April 30th, 2016||Deprecated|
|5.1 (PRR)||February 2012||April 30th, 2016||Deprecated|
|5.2 (PRR)||June 2012||April 30th, 2017||Deprecated|
|5.3 (PRR)||August 2012||April 30th, 2017||Deprecated|
|5.4 (PRR)||January 2013||Undetermined||Latest|
|5.4 (Conversations)||August 2016||Undetermined||Latest|
- These versions should not be expected to return data and/or may experience service degradation. Documentation specific to these versions may no longer be available. Bazaarvoice will provide one year advance notice before deprecating an API version.
- A deprecation date has been announced for these versions. Until that date they will continue to function. Applications using these versions should be upgraded to the latest version before the deprecation date to ensure continued functionality. New applications should NOT use these versions.
- Active versions continue to function, but applications using these versions should be upgraded to the latest version when possible to take advantage of new features and bug fixes. New applications should NOT use these versions.
- This is newest version. Feature development is focused on future versions, but we may perform backwards compatible bug fixes. New applications SHOULD use this version.
Refer to the Upgrade Guide and Changelogs to learn more about the differences between versions.
The API features you can use are dependent on your platform. The Conversations PRR platform has access to some features not available to Conversations platform.
- Conversations PRR
- This is the first Conversations platform. Originally called "Product Rating and Reviews" and later shortened to "PRR". On this platform client configurations are internal and all changes must be done by Bazaarvoice personnel. This platform is not available to new clients.
- Conversations is our latest platform. For this platform we've focused on best practices learned through our experience with the previous platform. This platform supports new features as well as the most valuable features from Conversations PRR, while eliminating poorly adopted or low value functionality. Clients on this platform have access to our self-service Configuration Hub, allowing them to see and interact with their configurations without relying on Bazaarvoice personnel.
Clients provisioned after mid 2013 are not likely to be on Conversations PRR and many older clients have already opted to migrate to Conversations.
How to determine your platform
Use one of the following methods to determine which platform you are on:
By API key
Enter a Conversations API key in the field below to learn the platform with which that key is associated.
⚠ Platform lookup unavailable. Please try one of the options below or contact our Bazaarvoice Support.
If you have access to your Bazaarvoice Workbench, log in and perform the following steps:
- Hover over "Settings" in the top menu
- If you see the option "Manage Applications" then you are on Conversations
- You may select "Manage Applications" to open the Configuration Hub
Contact our Support team who will be able to tell you on which platform your client instance is installed.
Feature availability and configuration
The Conversations API exposes a large number of features spread across several platforms. There are nine content types and over 30 different field types. Many of these are configurable, meaning their behavior and properties can be different from client to client. As a result, the features you see described in the Developer Portal may need additional configuration, may need to be enabled by default, or may not be available to you at all.
We understand that figuring out what features are available and how they are configured is challenging, so we've provided some tools to help:
- The API submission response
The API itself can be used to introspect available fields by omitting the
Actionparameter in a submission request. Learn more at the Submission Fundamentals tutorial.
- Conversations API Inspector
The API Inspector helps you see what fields are available for submission. The API Inspector makes a request without the
Actionparameter and displays the results in an easy to understand GUI. Open the Conversations API Inspector.
- Configuration Hub
If you are on the Conversations platform, you have access to a self-service configuration UI allowing you to see and interact with your configurations. Refer to the Workbench section above to learn how to navigate to the Configuration Hub.
- Bazaarvoice Support
If the above options don't work for you, then we can help.
We're thinking about the future of the Conversations API and we want you to be prepared. This section will help you to build applications with our Conversations API that are easier to upgrade to future API releases.
In the context of the Conversations API, future compatibility means gracefully accepting API responses generated by future API releases. A future compatible application is one that requires minimal code change to move to a newer API release.
How to improve future compatibility
- Always use the latest Conversations API version
We try to make each API release as backwards compatible as possible with the previous version. By using the latest version you can increase the likelihood that your application will work with newer API releases or at least minimize the work needed to upgrade.
See Versioning above for more details.
- Do not use Conversations PRR only features, even if you are still on the Conversations PRR platform
Conversations PRR only features are no longer supported on our newest Conversations platform. You should not expect them to be available in new API releases.
See Conversations PRR Only Features for a complete list.
- Try to avoid using features which we plan to deprecate in the future. These features are marked with a warning and are fully documented at Future deprecations.