Review answers

These endpoints are called from a shopper's browser, so they take your publishable key rather than a secret one. Anything specific to one customer also takes a signed email and timestamp: see Identifying the customer for how to produce the signature.

POST `/widgets/review-answers`

Ask a question about a product and get an answer generated from its published reviews, with the reviews it draws on. The answer is shown only to the shopper who asked; it is never published anywhere. Repeated questions are answered from cache. Only available when the store has review answers switched on, which GET /widgets/reviews reports as reviewAnswers.enabled.

Query Parameters

apiPublishableKeystringrequired

Your organization's publishable key, from Settings, API keys.

Body Parameters

productSlugstringrequired

Slug of the product the question is about.

questionstringrequired

The shopper's question, up to 300 characters.

visitorTokenstringrequired

Random id identifying the visitor's browser, used only for rate limiting. Only a hash of it is ever stored, and never with the question.

Request

curl \
  -X POST \
  "https://api.cascade.dev/widgets/review-answers?apiPublishableKey=pk_YOUR_PUBLISHABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "productSlug": "string",
  "question": "string",
  "visitorToken": "string"
}'

Request

import { client } from "@cascade-commerce/api/widget/client"
import { postWidgetsReviewAnswers } from "@cascade-commerce/api/widget"

client.setConfig({
  baseUrl: "https://api.cascade.dev",
})

const { data, error } = await postWidgetsReviewAnswers({
  query: { apiPublishableKey: "pk_YOUR_PUBLISHABLE_KEY" },
  body: {
    productSlug: "string",
    question: "string",
    visitorToken: "string",
  },
})

Request

require "net/http"

uri = URI("https://api.cascade.dev/widgets/review-answers?apiPublishableKey=pk_YOUR_PUBLISHABLE_KEY")
req = Net::HTTP::Post.new(uri)
req["Content-Type"] = "application/json"
req.body = <<~JSON
  {
    "productSlug": "string",
    "question": "string",
    "visitorToken": "string"
  }
JSON

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

Request

import json
from urllib.request import Request, urlopen

body = """{
  "productSlug": "string",
  "question": "string",
  "visitorToken": "string"
}"""

req = Request(
    "https://api.cascade.dev/widgets/review-answers?apiPublishableKey=pk_YOUR_PUBLISHABLE_KEY",
    data=body.encode(),
    headers={"Content-Type": "application/json"},
)
with urlopen(req) as res:
    print(json.load(res))

Response

{
  "answered": true,
  "answer": "string",
  "reviewCount": 0,
  "generatedAt": "string",
  "citedReviews": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "rating": 0,
      "title": "string",
      "excerpt": "string",
      "createdAt": "string"
    }
  ]
}

Response schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "answered": {
      "type": "boolean",
      "description": "True when the reviews address the question. False means the reviews do not say, which is an expected outcome rather than an error."
    },
    "answer": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "A short generated paragraph answering the question from the product's published reviews, in the language the question was asked in. Null when `answered` is false."
    },
    "reviewCount": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many published reviews the product had when the answer was generated."
    },
    "generatedAt": {
      "type": "string",
      "description": "When the answer was generated. Repeated questions are cached."
    },
    "citedReviews": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
            "description": "The review's id."
          },
          "rating": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "The review's star rating."
          },
          "title": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "The review's headline, if it has one."
          },
          "excerpt": {
            "type": "string",
            "description": "The start of the review's body, cut at 300 characters."
          },
          "createdAt": {
            "type": "string",
            "description": "When the review was written."
          }
        },
        "required": ["id", "rating", "title", "excerpt", "createdAt"],
        "additionalProperties": false
      },
      "description": "The published reviews the answer draws on. A review unpublished since the answer was generated is dropped from this list."
    }
  },
  "required": ["answered", "answer", "reviewCount", "generatedAt", "citedReviews"],
  "additionalProperties": false
}

#Review answers