Retrieve suggested product questions

Retrieve the questions to suggest about one product before the shopper has asked anything. This is the zero state of qna. Zero state is the term Constructor Autocomplete uses for what it shows before the shopper types: see Autocomplete examples.

The questions are the ones GET /v1/item_questions returns for the same request: questions curated in the dashboard, merged over the questions generated for the item ahead of time. Their order can differ between shoppers and between experiment arms. When the item has none, the index key's fallback questions are returned, if it has any. No question is generated during the request, and an unknown item_id is not an error.

The questions arrive as the options of one follow_up_refinement event. When there are none, the stream has no follow_up_refinement, and the JSON response has no follow_up_refinement field. On the stream, the start event's request carries zero_state: true, so it can be told apart from a qna answer.

To answer a question, send it unchanged as shopper_input to POST /v1/agent_insights/qna, with the same page_context, i, ui, features and feature_variants. A question can be answered from an answer stored for its exact text, so a changed string is answered live. Not every question has a stored answer, and some are always answered live.

parameters.num_questions sets the most questions to return. Without it, the number configured for the index key applies. The index key's question order can return fewer questions than either. page_context.item_id selects the product; page_context.variation_id and the other page_context fields are accepted but do not change the questions, which are kept per item.

Only key, c, ui, us, s, i, features and feature_variants change the result. The other agent insights query parameters are still validated, but have no effect here. A num_results query parameter, the count parameter of GET /v1/item_questions, is rejected with 400: send parameters.num_questions instead. The body takes no shopper_input and no request_context.

Migrating from GET /v1/item_questions

  • Method: GET /v1/item_questions sends everything in the query string; POST /v1/agent_insights/qna/zero_state sends a JSON body plus query parameters.
  • Response format: GET /v1/item_questions returns JSON; POST /v1/agent_insights/qna/zero_state streams SSE by default, or send Accept: application/json for one JSON document.
  • Item: ?item_id= and ?variation_id= become page_context.item_id and page_context.variation_id, plus the required page_context.page_type.
  • Count: ?num_results= becomes parameters.num_questions.
  • Questions: questions[].value becomes follow_up_refinement.options.
  • No questions: {"questions": []} becomes no follow_up_refinement.
  • Errors: GET /v1/item_questions answers an invalid request with 422; POST /v1/agent_insights/qna/zero_state answers with 400 and an AgentInsightsErrorResponse.
Query Params
string
required
length ≄ 1

The key of the index to use.

string

The ID of the client and version that the request is coming from, such as cio-js-2.90.

us
array of strings

A customer defined context (such as vip-club-member) used to evaluate redirect or refined tag rules. Pass multiple segments by passing multiple us arguments.

User segments
string

A customer generated anonymized identifier for a user on a customer website. It should only be sent for logged in customers and helps constructor to tie multiple client and session ID's together to form a behavioral data profile across devices.

feature_variants
object

Feature variants keyed by feature name. Accepts flattened feature_variants[<feature_name>] query parameters.

features
object

Feature toggles keyed by feature name. Accepts flattened features[<feature_name>] query parameters.

integer

An integer representing the user's session number (starting with 1), incremented after a 30 minute period of inactivity.

string

A globally unique identifier for the user browser (or mobile application instance) making the request.

Body Params

The request body for the qna zero state.

The request body for POST /v1/agent_insights/qna/zero_state. Carries only the product the suggested questions are about, and an optional cap on how many to return; it takes no shopper_input and no request_context.

page_context
object
required

The product the suggested questions are about. item_id is required.

parameters
object

Extra parameters for the zero state. The object may be omitted.

Headers
string
enum
Defaults to application/json

Generated from available response content types

Allowed:
Responses

Language
LoadingLoading…
Response
Choose an example:
application/json
text/event-stream