To implement guided selling through the API, use the Funnel endpoint.

The funnel takes an instancekey and a funnel code. Using that you can start a series of questions that will narrow the selected productset down to a selection based on the answers of the questions.

The implementation of a Guided Selling funnel should be done using the configuration in the response of the funnel requests. See Response.

Implementation

To start a Guided Selling funnel, follow these steps:

Set up some basic UI: a title, navigation (next, prev, reset) and maybe a progress bar to indicate the amount of questions.
Execute the funnel request to get the available questions to determine what to display. See Response.
Find the first question without an answer. Display the question and possible answers as desired using the provided configuration.
If a user makes a selection and wants to advance (using the navigation), execute the next funnel request by Providing answers and display the next question using nextquestionid.
If there are no more questions to display, the results of the funnel can be shown. See Display results.

Providing answers

To be able to traverse through the funnel, the API should know what answers were selected. This can be provided through the querystring, using the format qs{questionid}={answerid}.

For example, imagine this (simplified) scenario:

{
  "questions":[
    {
      "questionid":10,
      "question":"What size are you looking for?",
      "answers":[
        {
          "answerid":4,
          "answer":"Small"
        },
        {
          "answerid":8,
          "answer":"Big"
        }
     ]
}

To indicate that the user selected "Small", this would equate to qs10=4, resulting in the following request:

https://gateway.tweakwisenavigator.net/filterwizard/{instancekey}?code=gs-tv-nl&qs10=4

Display results

If there is no more question left to answer, the results should be displayed. The way Guided Selling results are processed usually is personal preference and more of a UX question. Frequently used options are:

Display products (recommended)
Redirect to a product lister page

Display products

The most frequently used option is to display the results as product tiles. This is the recommended way and the Tweakwise JS Guided Selling default.

The response contains an items list that can be used to display the items (products) as desired. This is the same information as exposed in the navigation, navigation-search or recommendations endpoints. See Items.

Saving results

In addition, it is recommended to "save" the result so the user can return back to the results once visiting a product from the selection. This could be done in many ways, a couple of frequently used options are:

Saving the entire response in session state
Saving the answers in hash or querystring (recommended)

const mapped = results.questions.map(o => {
	const selected = o.answers.find(o => o.isselected);
  if(selected){
    return `q${o.questionid}=${selected.answerid}`;
  }
  return null;
}).filter(o => o != null);

location.hash = 'twn-gs:' + mapped.join('&');

// on refresh, the hash can be used to initialize the first request using the saved answers

Redirect to a product lister page

In some cases, it makes sense to make the user land on a lister or search page.

The navigationurl in the Response is populated by us based on the answers provided. This can be used to generate a new URL to your lister page with filters already applied:

// navigationUrl = ?tn_cid=100093&tn_fk_size=Small&tn_ft=6
const pairs = results.navigationurl.replace('?', '').split('&');

const transformed = pairs.map(o => {
  const split = o.split('=');
  // the keys & values could be mapped to the platform URL structure
  return { 
    key: split[0].replace('tn_', '').replace('fk_', ''), 
    value: split[1]
  };
})

/* 
transformed will result in:
[
	{ key: 'cid', value: '100093' }, 
	{ key: 'size', value: 'Small' },
	{ key: 'ft', value: '6' }
];
*/

// would result in /search?cid=100093&size=Small&ft=6
const url = '/search?' + transformed.map(o => o.key + '=' + o.value).join('&');

The user could be redirect to the search page directly or the URL could be set to a link to give the control to the user.

Good to know

If a question has no answers, it can be skipped, no matter the value provided in skippable.
If you want to share a result, make sure you save the questions & answers somewhere (eg querystring), so the funnel request can be executed using those answers and the results will be displayed immediately.

Response

The JSON or XML response contain:

questions: the available questions & answers to display to the user. See Question.
items and count: the currently filtered selection of items. See Items.
navigationurl: an API URL to be able to execute a navigation request, corresponding to the current selection
filtertemplateid: the currently applied Filter Template

Question

questionid: the question identifier that should be used to mark an answer
question: the actual question text
explanation: a supporting text to the question
ismultiselect: indicating if one or more answers can be selected before advancing
imageurl: optional image to display along with the question
current: true/false indicating the current question
skippable and skiplabel: true/false to indicate if this question can be skipped using optional skiplabel
answers: List of answers. See answer
attribute: the connected attribute id, name and key

Answer

answerid: the answer identifer that should be used to mark an answer
answer: the actual answer text
caption: supporting text to the answer
summary: supporting explanation or summary for this answer
imageurl: optional image to display along with the question
count: amount of products left when this answer is selected
isselected: true/false to indicate if this answer is selected
nextquestionid: optional id of the next question to display when a selection is made
attributevalues: array of values that are mapped from the connected attribute