Writing flow content

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.

The content of a version decides how a flow behaves. The instruction holds your selling knowledge, the catalog lists what the flow may advise and the settings hold the opening question, the languages, the question budget and the model. You send the content whole when you create a flow or a new version, and it is the only thing the flow knows. The examples come from the label printer advisor in Creating and publishing a flow, which has the complete content.

The smallest content

A version needs an instruction, at least one product or cluster, the language you write in and an opening question with two options. Everything else has a default:

{
  "instruction": "Advise one of our two label printers. A customer who prints 1,000 labels a day or more needs the industrial one.",
  "catalogue": {
    "products": [
      { "productId": 18240, "name": "Desktop label printer" },
      { "productId": 18243, "name": "Industrial label printer" }
    ]
  },
  "settings": {
    "language": "EN",
    "opener": {
      "questions": [{ "language": "EN", "value": "How many labels do you print a day?" }],
      "options": [
        { "labels": [{ "language": "EN", "value": "Fewer than 1,000" }] },
        { "labels": [{ "language": "EN", "value": "1,000 or more" }] }
      ]
    }
  }
}

The sections below fill this out with the label printer advisor.

The instruction

The instruction is markdown, written for the AI model the way you would brief a new sales rep. It works best when it covers four things:

How to narrow down. The questions an expert asks, starting with the one that rules out the most products.
Rules. What rules a product in or out, in terms of the attributes in your catalog.
What goes with a product. The add-ons to offer with which products, and when.
What the advice should say. For example which needs each reason should name, or when to suggest talking to a specialist.

The instruction of the label printer advisor:

# Label printer advisor

You help warehouse managers, operations leads and office staff choose a label printer from this catalog.

## How to narrow down

1. Where the printer is used: a packing desk or office; a warehouse or production floor; on the move; or on a conveyor line, applying labels automatically.
2. How many labels the customer prints on a busy day.
3. The widest label they print: 2, 4 or 6 inch.
4. How the printer connects: USB, Ethernet, Wi-Fi or Bluetooth.

Rule printers out on what the customer tells you. Do not ask a question whose answer would not change the advice.

## Rules

- On the move means battery power and a wireless connection: only mobile printers fit.
- More than 5,000 labels a day needs an industrial printer.
- Labels wider than 4 inch need a 6-inch printer.
- Labels applied automatically on a conveyor need the LP-A800 print and apply system. Ask on which side of the conveyor it stands and advise that variant. Boxes of different heights need the air blow applicator. Add the missing label sensor when the customer must not ship a box without a label, and the service plan only when they ask for on-site service.
- Thermal transfer labels last longer than direct thermal ones. Mention it when labels are stored outdoors or for months.
- When the customer already knows which model they want, ask which one and advise it.

## With the printer

Offer one box of thermal transfer ribbons with every industrial printer and print and apply system when labels are stored outdoors or for months.

## In the advice

In each reason, name the customer's needs that the printer meets. When no printer here meets a need, say so and suggest talking to a specialist.

What helps:

Describe how an expert rules products out rather than which product to pick. The flow asks whichever question best splits the products that still fit.
Use the attribute names and values of your catalog in your rules, so rules and products clearly match.
For a cluster, say which answers decide the variant and when a cluster option is needed.
Put every fact the flow may use in the catalog or the instruction. The flow does not state facts that are in neither.
Leave out what every flow already does, such as limiting the number of options or never naming prices. See Rules every flow follows.

The catalog

The catalog lists what the flow may advise, with only what it needs to choose. It has two lists: products and clusters. A catalog can hold either or both.

Products

Field	What to put in it
`productId`	The Propeller product id. The advice returns it and the storefront fetches the product with it.
`sku`	Optional. For people who read the content and the conversation history. The flow does not use it to decide.
`name`	The product name as the flow should know it
`description`	One line on what the product is for, in the words a buyer would use
`attributes`	The attributes that tell products apart, each as a name and a text value. Join the values of a multi-valued attribute in one string.

{
  "productId": 18242,
  "sku": "LP-M220",
  "name": "LP-M220 Mobile Label Printer",
  "description": "Battery-powered printer worn on the belt for shelf and picking labels.",
  "attributes": [
    { "name": "ENVIRONMENT", "value": "Warehouse aisles, customer sites" },
    { "name": "LABELS_PER_DAY", "value": "Up to 300" },
    { "name": "MAX_LABEL_WIDTH", "value": "2 inch" },
    { "name": "PRINT_METHOD", "value": "Direct thermal" },
    { "name": "CONNECTIVITY", "value": "Bluetooth, Wi-Fi" },
    { "name": "POWER_SOURCE", "value": "Battery" }
  ]
}

Clusters

List a cluster when the flow should advise it as a configuration: one of its variants with a product for each cluster option it needs. The flow chooses the variant and the option products from the customer's answers and your instruction, and the storefront adds the configuration to the cart in one call.

Field	What to put in it
`clusterId`	The Propeller cluster id
`sku`, `name`, `description`, `attributes`	As for a product. The attributes the variants share go on the cluster.
`variants`	The products of the cluster the flow may advise, with the attributes that tell them apart
`defaultVariantId`	Optional. The variant to advise when nothing in the answers points to another.
`options`	The cluster options, each with its `clusterOptionId`, `name`, `description`, `isRequired`, `defaultProductId` and `products`
`options.isRequired`	`true` when every configuration needs a product for this cluster option. The flow always fills it.
`options.defaultProductId`	Optional. The product that fills a required cluster option when the model leaves it out.
`options.products.defaultQuantity`	How many of the product go with one configured cluster. Defaults to 1.
`options.products.maxQuantity`	Optional. Without it, the quantity is always `defaultQuantity`. With it, the flow chooses 1 to `maxQuantity` from the answers.

The print and apply system of the label printer advisor:

{
  "clusterId": 1830,
  "sku": "LP-A800",
  "name": "LP-A800 Print and Apply System",
  "description": "Prints labels and applies them to boxes on a conveyor line, without an operator.",
  "attributes": [
    { "name": "ENVIRONMENT", "value": "Conveyor line" },
    { "name": "LABELS_PER_DAY", "value": "Up to 20,000" },
    { "name": "MAX_LABEL_WIDTH", "value": "4 inch" },
    { "name": "PRINT_METHOD", "value": "Thermal transfer" }
  ],
  "variants": [
    {
      "productId": 18301,
      "sku": "LP-A800-L",
      "name": "LP-A800 Print and Apply System, left-hand",
      "attributes": [{ "name": "CONVEYOR_SIDE", "value": "Left" }]
    },
    {
      "productId": 18302,
      "sku": "LP-A800-R",
      "name": "LP-A800 Print and Apply System, right-hand",
      "attributes": [{ "name": "CONVEYOR_SIDE", "value": "Right" }]
    }
  ],
  "defaultVariantId": 18302,
  "options": [
    {
      "clusterOptionId": 1831,
      "name": "Applicator",
      "isRequired": true,
      "defaultProductId": 18311,
      "products": [
        { "productId": 18311, "sku": "LP-A800-TAMP", "name": "Tamp applicator", "description": "Presses the label onto the box. For boxes of one height." },
        { "productId": 18312, "sku": "LP-A800-BLOW", "name": "Air blow applicator", "description": "Blows the label onto the box. For boxes of different heights." }
      ]
    },
    {
      "clusterOptionId": 1832,
      "name": "Label sensor",
      "isRequired": false,
      "products": [
        { "productId": 18321, "sku": "LP-A800-SENS", "name": "Missing label sensor", "description": "Stops the line when a box leaves without a label. One per conveyor lane.", "defaultQuantity": 1, "maxQuantity": 2 }
      ]
    },
    {
      "clusterOptionId": 1833,
      "name": "Service plan",
      "isRequired": false,
      "products": [
        { "productId": 18331, "sku": "SVC-ONSITE-3Y", "name": "3-year on-site service", "description": "A technician on site within one business day, for three years." }
      ]
    }
  ]
}

List only the variants and cluster options you want advised, with the same ids as in Propeller, so the storefront can add the configuration to the cart. Propeller's cart checks that each option product belongs to the cluster.

Add-ons

Add-ons are products the flow offers with an advised product, such as consumables, accessories or a service. List each one in products and say in the instruction which add-ons go with which products, and when. The flow offers an add-on only from products, never a cluster, and never the advised product itself or one of its option products. The ribbons of the label printer advisor:

{
  "productId": 18250,
  "sku": "TTR-110-450",
  "name": "Thermal transfer ribbon 110 mm x 450 m, box of 12",
  "description": "Wax-resin ribbons for long-lasting labels on industrial printers and print and apply systems."
}

A product in products can be advised on its own as well, so describe it in the words a buyer would use.

What helps

Include only attributes that differ between products and matter to a buyer. An attribute that every product shares cannot help the flow choose.
Leave out prices, stock and images. The storefront shows them per customer.
List the products you want advised, typically one product range. A flow advises from the same catalog for every customer, and the storefront leaves out advised products a customer cannot buy.

Build the catalog from your product data in Propeller, for example with the products and cluster queries. The catalog is a copy: when products or their data change, the flow does not change with them. Create a new version with the updated catalog and publish it.

Every step sends the instruction and the catalog to the model. The model vendor caches them, but a shorter instruction and only the attributes that matter still keep steps faster and cheaper.

The settings

The settings of the label printer advisor:

{
  "language": "EN",
  "languages": ["EN", "NL"],
  "opener": {
    "questions": [
      { "language": "EN", "value": "Where will the printer be used?" },
      { "language": "NL", "value": "Waar gaat u de printer gebruiken?" }
    ],
    "options": [
      {
        "labels": [
          { "language": "EN", "value": "At a packing desk or in an office" },
          { "language": "NL", "value": "Aan een inpaktafel of op kantoor" }
        ]
      },
      {
        "labels": [
          { "language": "EN", "value": "In a warehouse or on the production floor" },
          { "language": "NL", "value": "In een magazijn of in de productie" }
        ]
      },
      {
        "labels": [
          { "language": "EN", "value": "On the move: in the aisles or at customer sites" },
          { "language": "NL", "value": "Onderweg: tussen de stellingen of bij klanten" }
        ]
      },
      {
        "labels": [
          { "language": "EN", "value": "On a conveyor line, applying labels automatically" },
          { "language": "NL", "value": "Aan een transportband, automatisch etiketteren" }
        ]
      },
      {
        "labels": [
          { "language": "EN", "value": "I already know which model I want" },
          { "language": "NL", "value": "Ik weet al welk model ik wil" }
        ]
      }
    ]
  },
  "freeText": true,
  "maxQuestions": 5,
  "model": { "model": "claude-sonnet-5-5", "effort": "MEDIUM" }
}

Setting	What it does	Default
`language`	The language you wrote the content in, as a two-letter code such as `EN`	Required
`languages`	The languages the flow answers in, as two-letter codes	`language` only
`opener`	The opening question and its options, written per language	Required
`freeText`	Whether customers may type an answer instead of picking an option	`true`
`maxQuestions`	The question budget: the most answers a customer gives before the advice	`6`
`model.model`	The Anthropic model id, for example `claude-sonnet-5-5`	The platform default, now `claude-sonnet-5-5`
`model.effort`	How hard the model thinks on every step: `LOW`, `MEDIUM` or `HIGH`	`MEDIUM`

The opening question

The opening question is shown instantly and without a model call, so make it the question that splits your catalog best and that every customer can answer, such as where or for what the product is used. Give it two to six options with distinct labels.

An option for customers who already know what they want, together with a rule in the instruction, gives experienced buyers a short way through.

Languages

You write the instruction and the catalog once, in language. The flow writes its questions and advice in the language of each request, for every language in languages. Only the opening question and its options are written per language. Write them in every language you offer: validation refuses content whose opening question or option labels miss one of them.

Typed answers

With freeText set to true, customers can type an answer to every question. Typed answers let customers explain what the options do not cover, but every step after a typed answer is a model call for that customer and takes several seconds. Set it to false for a flow with options only.

The question budget

maxQuestions counts every answer, picked or typed, the answer to the opening question included. The flow advises as soon as the answers identify the fit, so most conversations end before the budget is spent. When it is spent, the next step is the advice. A budget of 4 to 6 suits most catalogs.

Model and effort

Leave model.model out to use the platform default, now claude-sonnet-5-5, or name an Anthropic model to fix the flow to it. Naming it is better: the flow keeps the model you tested when the default changes, and its content shows which model it runs. A flow on the default reads back model as null.

Every model call is billed to the flow's key at the price of its model, and prices differ a lot: per token, claude-sonnet-5-5 costs about twenty times as much as claude-haiku-5-5. A flow makes model calls before any customer uses it, too: publishing a version prepares its first steps in every language, and replacing the key or switching the flow on can prepare them again.

Guided selling asks Anthropic whether it knows the model when you create the flow and when you publish a version. A model Anthropic does not know stops either one with GUIDED_SELLING_MODEL_UNAVAILABLE_ERROR and the reason LLM_MODEL_NOT_FOUND. A new draft is not checked when you create it: testing it with an unknown model fails the step with the same reason.

model.effort applies to every step, questions and advice alike, so that they share the model vendor's cache. A higher effort is slower and costs more. Try a different model or effort on a draft before you publish it.

Limits

Content	Limit
Flow `name`	1 to 255 characters
`modelApiKey`	8 to 512 characters
`instruction`	1 to 200,000 characters
The whole content	Up to 500,000 characters: instruction, catalog and settings together
Catalog	At least one product or cluster. Up to 2,000 different products, variants and option products together.
Product `name`	1 to 300 characters
`sku`	Up to 100 characters
`description`	Up to 2,000 characters
`attributes`	Up to 50 per product or cluster. Name 1 to 100 characters, value up to 500.
Cluster `variants`	1 to 50 per cluster, each once
Cluster `options`	Up to 20 per cluster, each once, with 1 to 50 products each
`defaultQuantity`, `maxQuantity`	1 to 1,000, and `defaultQuantity` at most `maxQuantity`
`language` and each of `languages`	Two letters
`languages`	Up to 20
Opening question	Up to 300 characters
Opening question options	2 to 6, labels up to 120 characters and distinct within a language
`maxQuestions`	1 to 20
`model.model`	Up to 100 characters

Validation

Guided selling validates the content when you create a flow or a version and reports every problem at once. A field that breaks its rule, such as an opening question with one option or a name that is too long, returns BAD_REQUEST with each broken rule in extensions.originalError.message:

{
  "errors": [
    {
      "message": "Bad Request Exception",
      "path": ["guidedSellingFlowVersionCreate"],
      "extensions": {
        "code": "BAD_REQUEST",
        "originalError": {
          "message": ["content.settings.opener.options must contain at least 2 elements"],
          "error": "Bad Request",
          "statusCode": 400
        }
      }
    }
  ],
  "data": null
}

Content that does not fit together returns GUIDED_SELLING_CONTENT_INVALID_ERROR, with each problem in extensions.problems:

{
  "errors": [
    {
      "message": "The flow content is invalid.",
      "path": ["guidedSellingFlowCreate"],
      "extensions": {
        "code": "GUIDED_SELLING_CONTENT_INVALID_ERROR",
        "problems": [
          "settings.opener.questions: no question in the authored language EN",
          "catalogue.products[5]: productId 18240 listed twice"
        ]
      }
    }
  ],
  "data": null
}

Content checks include:

the catalog holds at least one product or cluster
every product, cluster, variant, cluster option and option product is listed once in its list
defaultVariantId is one of the cluster's variants and defaultProductId one of its cluster option's products
defaultQuantity is not above maxQuantity
the opening question and every option have a text in language and in each of languages, within the length limits
option labels are distinct within a language

The smallest content​

The instruction​

The catalog​

Products​

Clusters​

Add-ons​

What helps​

The settings​

The opening question​

Languages​

Typed answers​

The question budget​

Model and effort​

Limits​

Validation​

See also​