Content Coach

What is Content Coach?

The Content Coach improves review quality by providing real-time, AI-powered topic suggestions to write a review. Using product details such as the product name and description, Content Coach generates five relevant review topics that help consumers write more specific and useful feedback.

ℹ️

Note:

1. The Content Coach can be implemented for English, Spanish, French, and German locales.
2. This feature is a part of the Conversations API.

Endpoints included

The Content Coach includes two endpoints:

• review-tokens—Returns topic suggestions for a product within the submission form. This returns five single-word topics.
• matched-tokens—Returns topic suggestions that match the review text as consumers type. The review text must contain a minimum of five words for the endpoint to return results.

How to implement Content Coach

1. When the submission form opens, implement logic to send a request to the review-tokens endpoint with the productId and passkey.
2. The review-tokens endpoint returns up to five AI-generated topic suggestions.
3. Implement logic to display the topic suggestions in the submission form.
4. Implement logic to call the matched-tokens endpoint after the consumer enters the first five words, and call it again only after each subsequent word is completed (for example, after the sixth word, seventh word, and so on). Ensure the request body contains productId and reviewText.
5. The matched-tokens endpoint analyzes the review text against the suggested topics and returns a list of matching topics (array).
6. Implement logic to use the response to highlight relevant topic sections in real time, indicating which topics are already covered in the review.
7. Implement logic to highlight the matching topics. This indicates that those topics are covered in the review text.

Technical requirement (Mandatory)

When implementing logic to call the matched-tokens endpoint, you must invoke the endpoint after the consumer enters the first five words. Call it again only after each subsequent word is completed (for example, after the sixth word, seventh word, and so on)

❗️

Important:

Clients are expected to follow this logic exactly. Excessive or non-compliant API calls may result in service suspension at Bazaarvoice’s discretion. Use the rate-limit headers in each response to monitor API usage.

Retrieve AI-generated topics using review-tokens endpoint

When the consumer opens the submission form, send a request with the productId as a query parameter and the passkey within the bv-passkey HTTPS header.

The technical specifications are as follows:

Endpoint

[GET] /data/content-coach/v1/review-tokens

HTTPS Method

GET

URL

https\://[stg].api.bazaarvoice.com/data/content-coach/v1/review-tokens?productId=8006540519714&locale=en_US 
--header 'bv-passkey: <passkey>

Parameters

ℹ️

Note:

Parameters marked with an asterisk (*) are mandatory.

Example call

https://stg.api.bazaarvoice.com/data/content-coach/v1/review-tokens?productId=<productId>

Example response

{
   "data": [
       "Performance",
       "Comfort",
       "Design",
       "Stability",
       "Safety"
   ],
   "status": 200,
   "type": "",
   "title": "",
   "detail": ""
}

Retrieve matched topics using matched-tokens endpoint

1. When the consumer has completed typing a minimum of 5 words in the Review text box, call matched-tokens endpoint with productId and reviewText as request body parameters.
2. Make the next call only after each subsequent word is completed (for example, after the sixth word, seventh word, and so on).

The technical specifications are as follows:

Endpoint

[POST] /data/content-coach/v1/matched-tokens

HTTPS Method

POST

URL

https\://[stg].api.bazaarvoice.com/data/content-coach/v1/matched-tokens?locale=en_US 
--header 'bv-passkey: <passkey>

Parameters

ℹ️

Note:

Parameters marked with an asterisk (*) are mandatory.

Example call

curl 'https://stg.api.bazaarvoice.com/data/matchedtokens?locale=en_US' \
--header 'Content-Type: application/json' \
--header 'bv-passkey: <passkey>' \
--data '{
  "productId": "<productId>",
  "reviewText": "The bike combines modern design with smooth performance, making every ride enjoyable. It offers excellent comfort, even on longer rides or rough roads."
}'

Example response

{
   "data": [
     "Design",
     "Performance"
     "Comfort"
   ],
   "status": 200,
   "type": "",
   "title": "",
   "detail": ""
}

Rate limit headers

Every API response includes the following headers to help you monitor your API rate limit:

Success

Errors