--- updatedAt: 2026-10-06T08:08:24.000Z agentTools: projectIndex: https://developers.bazaarvoice.com/v1.0-ConversationsAPI/llms.txt --- # Content Coach This section outlines the purpose of the Content Coach feature and provides implementation guidance, including sample request and response. # 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**, **German**, **Portuguese**, **Arabic**, **Japanese, Dutch** and **Italian** locales. 2. This feature is a part of the **Conversations API**. # Tutorial For a detailed video tutorial refer here # 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`, `locale` 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 an array of matching topics based on **implicit meaning, even when the exact words do not appear in the review text.** 6. Implement logic to use the response to highlight relevant topic sections in real time, indicating which topics are already covered in the review. # 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](https://developers.bazaarvoice.com/docs/content-coach#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` and `locale` 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 ```julia URL https\://[stg].api.bazaarvoice.com/data/content-coach/v1/review-tokens?productId=8006540519714&locale=en_US --header 'bv-passkey: ``` ## Parameters ### Note: Parameters marked with an asterisk (\*) are mandatory. | Parameter | Placement | Data type | Description | | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | productId\* | Query | String | Use the productId from the Bazaarvoice product catalog for the client instance.
**Note:** Ensure the productId matches the one saved in the Bazaarvoice product catalog.
**Example:**., P-7777-MSD | | bv-passkey \* | Header | String | A **Conversations API passkey** for authentication. This is a query parameter, which is a part of the request URL | | locale\*
**Format:** languageCode\_countryCode Any other format will return a bad request response | Query | String | Indicates the client-configured locale to get localized topics. Topics will be provided as per the requested locale. The [supported locales](https://developers.bazaarvoice.com/v1.0-ConversationsAPI/docs/internationalization#supported-locales) are English (en\_\*), German (de\_\*), French (fr\_\*), Spanish (es\_\*), Portuguese (pt\_*), Arabic (ar\_*), Japanese (ja\_\*), Dutch (nl\_\*) and Italian (it\_\*) | ## Example call `https://stg.api.bazaarvoice.com/data/content-coach/v1/review-tokens?productId=&locale=` ## Example response ```javascript { "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 ```julia URL https://[stg].api.bazaarvoice.com/data/content-coach/v1/matched-tokens?locale=en_US --header 'bv-passkey: ``` ## Parameters ### Note: Parameters marked with an asterisk (\*) are mandatory. | Parameter | Placement | Data type | Description | | :---------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | productId\* | Request body | String | Use the productId from the Bazaarvoice product catalog for the client instance. **Note:** Ensure the product ID matches the one saved in the Bazaarvoice product catalog. (e.g., `P-7777-MSD`). | | reviewText\* | Request body | String | The user-written review. Requires a minimum of 5 words. | | bv-passkey\* | Header | String | A **Conversations API passkey** for authentication. This should be sent through the HTTP header. | | locale\*
**Format:** languageCode\_countryCode Any other format will return a bad request response | Query | String | Indicates the client-configured locale to get localized topics. Topics will be provided as per the requested locale.
The [supported locales](https://developers.bazaarvoice.com/v1.0-ConversationsAPI/docs/internationalization#supported-locales) are English (en\_*), German (de\_*), French (fr\_*), Spanish (es\_*), Portuguese (pt\_\_), Arabic (ar\_\_),Japanese (ja\_\*),Dutch (nl\_\*) and Italian (it\_\*) | ## Example call ``` curl 'https://stg.api.bazaarvoice.com/data/matchedtokens?locale=en_US' \ --header 'Content-Type: application/json' \ --header 'bv-passkey: ' \ --data '{ "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 ```javascript { "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: | Header | Description | Example value | | :------------------ | :------------------------------------------------------- | :----------------------- | | ratelimit-limit | Maximum number of requests allowed in the current window | 600 | | ratelimit-remaining | Number of requests remaining in the current window | 578 | | ratelimit-reset | ISO 8601 timestamp when the rate limit window resets | 2026-01-30T10:00:00.000Z | | ratelimit-policy | Rate limit policy describing the window sizes | 600;w=60, 600;w=3600 | ## Success
Success code Endpoint When this happens Response
200 review-tokens The `productId` is valid, and it has a defined product name. Returns 5 AI-generated topics.
matched-tokens The `reviewText` contains 5 or more words Returns the matched topics as an array.
204 review-tokens The `productId` is valid, but no AI suggestions are available for that product. Returns an empty response. **Note:** This may occur due to insufficient product details. To learn how to edit product details in the Bazaarvoice Portal, refer to [Edit products](https://docs.bazaarvoice.com/articles/#!ratings-reviews/product_catalog/a/edit-products).
matched-tokens The `reviewText` does not match any of the suggested topics. Returns an empty response.
## Errors | Error code | Description | | :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 - Bad Request | Illegal empty query param: productId/locale | | 403 - Forbidden | Permission denied for this client/product. | | 404 - Not Found | Resource not found. | | 406 - Language not supported | The requested locale is not supported. | | 422 - Review text too short | Invalid review text. A minimum of 5 words is required. | | 429 - API rate limit | The maximum API rate limit is reached.
**Note:** Contact [Bazaarvoice Support](https://developers.bazaarvoice.com/v1.0-TransactionsAPI/page/support) for assistance. | | 503 - Service Unavailable | Upstream AI service is temporarily unavailable. | | 500 - Internal Error | Something went wrong. Please try again later. |