Skip to main content

guidedSellingStep

BETA: guided selling can still change in ways that break existing integrations. Backwards compatibility is not guaranteed while it is in beta.

The whole storefront contract: one step of a guided selling conversation. With no answers it returns the authored opening question, instantly. With the answers so far it returns either the next question with its options or the advice.

A mutation: every call is recorded in the conversation history, and a step nobody computed before spends the tenant's model budget. The result is stored and reused for every customer who gives the same answers, so repeating a call is safe: it returns the same step while that step is stored. Call it from the shop's server with one fixed operation, never from the browser, and do not cache it. One step per operation, aliases and fragments included. A step that needs the model takes at most 45 seconds of model work, its one retry included; give the call a timeout a little above that.

Possible errors:

  • BAD_REQUEST: a field breaks its rule (a malformed flow id, a language that is not two letters, more than 20 answers, a text too long); extensions.originalError.message names each
  • GUIDED_SELLING_FLOW_NOT_FOUND_ERROR: unknown flow
  • GUIDED_SELLING_FLOW_VERSION_NOT_FOUND_ERROR: (configuration.EDITOR or OWNER) the pinned version does not exist
  • GUIDED_SELLING_FLOW_VERSION_NOT_ALLOWED_ERROR: the caller may not run this version: a storefront runs the published version, or the one its conversation started on; naming another version or running a draft needs configuration.EDITOR or OWNER
  • GUIDED_SELLING_FLOW_INACTIVE_ERROR: the flow is switched off (a storefront call; configuration.EDITOR or OWNER can still test it)
  • GUIDED_SELLING_FLOW_NOT_PUBLISHED_ERROR: no version is published and none was pinned
  • GUIDED_SELLING_LANGUAGE_UNSUPPORTED_ERROR: not one of the flow's languages; retry in one of extensions.supported
  • GUIDED_SELLING_ANSWER_UNKNOWN_ERROR: an answer this flow did not ask for, an expired one, or one sent in another language than its question; start again, silently, with a new conversationId
  • GUIDED_SELLING_INPUT_INVALID_ERROR: the input breaks a rule a field cannot express (both or neither of optionId and text, typed text where typing is off, more answers than the flow's question budget, a conversationId that belongs to another flow); extensions.problems names each. An integration bug: log it
  • GUIDED_SELLING_QUOTA_EXCEEDED_ERROR: the tenant's model-call budget is spent, shared by all its flows; extensions.reason says which and extensions.retryAfterMs for how long. MINUTE: the per-minute budget; say the advisor is busy and to try again shortly. DAY: the cap for the last 24 hours; hide the advisor until retryAfterMs has passed. The opener and steps that were computed before keep working
  • GUIDED_SELLING_MODEL_UNAVAILABLE_ERROR: the model vendor failed or timed out; extensions.reason and extensions.retryable. Retryable: LLM_TIMEOUT, LLM_RATE_LIMITED, LLM_UNAVAILABLE (vendor 5xx and network errors), LLM_BAD_OUTPUT; offer Try again. Not retryable: LLM_AUTH_FAILED (the flow's key was refused), LLM_MODEL_NOT_FOUND, LLM_BAD_REQUEST, LLM_REFUSED; hide the advisor and log it. The step is kept in the conversation history with the vendor's own words
  • GUIDED_SELLING_TURN_FAILED_ERROR: no valid step after a retry. Not stored, so a retry computes it again; offer Try again and Start over. Kept in the conversation history with the problems

An advice can have no items: when nothing in the catalogue can meet what the customer needs, its headline says so. Offer a way to contact a specialist then.

AUTH: any API key, with or without a user token (a storefront visitor or a logged-in user). Naming a version other than the published one needs Role=[configuration.OWNER,configuration.EDITOR].

guidedSellingStep(
input: GuidedSellingStepInput!
): GuidedSellingStepResult!

Arguments​

guidedSellingStep.input ● GuidedSellingStepInput! non-null input​

The full conversation state: every answer so far, in order. Send everything, every call; the runtime keeps no session.

Type​

GuidedSellingStepResult union​

BETA: guided selling can still change in ways that break existing integrations. Backwards compatibility is not guaranteed while it is in beta.

Either the next question or the advice.