Skip to main content

Conversations and conversion

Not yet available

Guided selling is not yet available. This page describes it ahead of its release, so details can still change. The changelog announces when it is released.

Guided selling records every conversation: each step as the customer saw it, the model calls behind it and what the storefront reported about the advice. The statistics show how a flow converts and the history shows why.

Measuring conversion​

guidedSellingFlowStats counts the conversations of a flow:

query FlowStats($input: GuidedSellingFlowStatsInput!) {
  guidedSellingFlowStats(input: $input) {
    flowId
    version
    conversations
    adviceReached
    adviceShown
    addedToCart
    productsAddedToCart
  }
}

Variables:

{
  "input": {
    "flowId": "01a10f3c-5b7e-7d42-9a61-3c8e2f4b7d90",
    "version": 1,
    "createdAt": { "greaterThan": "2026-10-01T00:00:00Z" }
  }
}

Expected response:

{
  "data": {
    "guidedSellingFlowStats": {
      "flowId": "01a10f3c-5b7e-7d42-9a61-3c8e2f4b7d90",
      "version": 1,
      "conversations": 412,
      "adviceReached": 287,
      "adviceShown": 281,
      "addedToCart": 64,
      "productsAddedToCart": 91
    }
  }
}
FieldWhat it counts
conversationsConversations that started
adviceReachedConversations that reached the advice
adviceShownConversations whose advice the storefront reported as shown
addedToCartConversations in which the customer added an advised product to the cart
productsAddedToCartAdvised products added to carts, quantities included

Every count except productsAddedToCart is a number of conversations. adviceShown, addedToCart and productsAddedToCart depend on the storefront reporting outcomes, see Reporting outcomes.

Both filters are optional. version counts only conversations on that version, which lets you compare versions. createdAt selects conversations by the moment of their first step. Conversations you run to test a draft count toward that version too.

Listing conversations​

query Conversations($input: GuidedSellingConversationSearchInput) {
  guidedSellingConversations(input: $input) {
    itemsFound
    items {
      id
      version
      language
      turnCount
      completed
      createdAt
    }
  }
}

Variables:

{
  "input": {
    "flowId": "01a10f3c-5b7e-7d42-9a61-3c8e2f4b7d90",
    "offset": 2
  }
}

Expected response:

{
  "data": {
    "guidedSellingConversations": {
      "itemsFound": 412,
      "items": [
        {
          "id": "3f6c1a52-8e0b-4d7a-9c2e-5b8f0d4a7e19",
          "version": 1,
          "language": "EN",
          "turnCount": 3,
          "completed": true,
          "createdAt": "2026-10-06T13:20:31.000Z"
        },
        {
          "id": "b0d9e7a4-1c62-4f35-8e1d-7a2c9f6b3e58",
          "version": 1,
          "language": "NL",
          "turnCount": 2,
          "completed": false,
          "createdAt": "2026-10-06T13:12:07.000Z"
        }
      ]
    }
  }
}

The most recent conversations come first. id is the conversationId the storefront sent. turnCount is the number of steps served, the opening question included. completed is true once the conversation reached the advice. Filter with flowId and createdAt, and page through the results with page and offset.

Reading a conversation​

guidedSellingConversation returns one conversation with every step and every outcome:

query Conversation($id: ID!) {
  guidedSellingConversation(id: $id) {
    id
    version
    language
    completed
    turns {
      index
      cacheClass
      answers {
        question
        answer
        typed
      }
      question {
        question
      }
      advice {
        headline
        items {
          productId
          reason
        }
      }
      error {
        code
        reason
      }
      modelCalls {
        speculative
        model
        effort
        outcome
        inputTokens
        outputTokens
        cacheReadInputTokens
        latencyMs
      }
    }
    outcomes {
      event
      productIds
      quantity
      createdAt
    }
  }
}

Expected response:

{
  "data": {
    "guidedSellingConversation": {
      "id": "3f6c1a52-8e0b-4d7a-9c2e-5b8f0d4a7e19",
      "version": 1,
      "language": "EN",
      "completed": true,
      "turns": [
        {
          "index": 1,
          "cacheClass": "STATIC",
          "answers": [],
          "question": { "question": "Where will the printer be used?" },
          "advice": null,
          "error": null,
          "modelCalls": []
        },
        {
          "index": 2,
          "cacheClass": "HIT",
          "answers": [
            { "question": "Where will the printer be used?", "answer": "In a warehouse or on the production floor", "typed": false }
          ],
          "question": { "question": "How many labels do you print on a busy day?" },
          "advice": null,
          "error": null,
          "modelCalls": [
            {
              "speculative": true,
              "model": "claude-sonnet-5-5",
              "effort": "MEDIUM",
              "outcome": "QUESTION",
              "inputTokens": 402,
              "outputTokens": 913,
              "cacheReadInputTokens": 3874,
              "latencyMs": 6120
            }
          ]
        },
        {
          "index": 3,
          "cacheClass": "COLD",
          "answers": [
            { "question": "Where will the printer be used?", "answer": "In a warehouse or on the production floor", "typed": false },
            { "question": "How many labels do you print on a busy day?", "answer": "About 8,000 a day, mostly 6-inch pallet labels", "typed": true }
          ],
          "question": null,
          "advice": {
            "headline": "An industrial 6-inch printer for your daily pallet labels",
            "items": [
              {
                "productId": 18241,
                "reason": "It prints up to 10,000 labels a day on labels up to 6 inch wide, so it handles your 8,000 pallet labels a day."
              }
            ]
          },
          "error": null,
          "modelCalls": [
            {
              "speculative": false,
              "model": "claude-sonnet-5-5",
              "effort": "MEDIUM",
              "outcome": "ADVICE",
              "inputTokens": 455,
              "outputTokens": 1288,
              "cacheReadInputTokens": 3874,
              "latencyMs": 8740
            }
          ]
        }
      ],
      "outcomes": [
        { "event": "ADVICE_SHOWN", "productIds": [18241], "quantity": null, "createdAt": "2026-10-06T13:21:09.000Z" },
        { "event": "ADDED_TO_CART", "productIds": [18241], "quantity": 1, "createdAt": "2026-10-06T13:21:52.000Z" }
      ]
    }
  }
}

Each turn holds the answers given before it and the question, the advice or the error that the customer got. cacheClass tells how the step was produced, which is what decided how long the customer waited:

cacheClassHow the step was produced
STATICThe opening question, from the settings. No model call.
HITA stored step, usually one prepared in advance
INFLIGHTA step that was already being prepared for the same answers when the customer asked for it
COLDWritten by the model for this request, while the customer waited

modelCalls lists the model calls behind a step. speculative is true for calls made in advance, when nobody was waiting. outcome is one of:

outcomeMeaning
QUESTIONA valid next question
ADVICEA valid advice
REJECTEDA step that failed the check, for example a product id that is not in the catalog. Guided selling tries once more.
ERRORThe call to the model failed or timed out

Improving a flow with the history​

  • Typed answers (typed: true) show what customers want to say that the options do not cover. Turn answers that come back often into a rule in the instruction or an option of the opening question.
  • Steps with an error show what customers ran into. error.code is the code the storefront received and error.reason says why, for example the model vendor's own words for a refused key or the problems of a step that failed the check twice.
  • Conversations that do not complete show where customers stop.
  • Model calls show what each step cost. inputTokens and outputTokens are billed at the vendor's full rate and cacheReadInputTokens at a fraction of it.
  • Versions can be compared with guidedSellingFlowStats, filtered by version.

Personal data​

What customers type can contain personal data. Guided selling stores it with the conversation until you delete the flow, and deleting the flow deletes all of its conversations. Only keys and users with Owner access on the Configuration role can read conversations. The statistics contain no text from conversations.

The conversationId and the outcome reports carry no customer identity, so a recorded conversation is not linked to a customer account. Make sure your storefront does not put personal data in the conversationId.

See also​