Table of Contents

Ticket Widget: Form Results and State Across Steps

Helpdocs Admin Updated by Helpdocs Admin

Every widget response can include two properties, form and state. They let your API pass information from one step to the next without storing anything itself.

In short: the UI sends the form and state of the widget it is currently showing along with the next request. Whatever you put in a response comes back to you on the following one.

This is an advanced topic. Read the Form article and How the Widget Is Requested first.

The rule

When the UI requests a widget, it sends the form and state it currently holds. The UI keeps answers while the page stays open, and sends all of them, not only the current field's.

  • Next step: the request carries every answer the UI holds, plus the state it holds.
  • Page reload, or opening a new ticket: there is no widget on screen yet, so form is empty and state is not sent. The flow starts from the beginning.

The UI keeps nothing else. It does not remember earlier widgets or choices.

state

state holds text keys with text values. It is yours to use. The UI sends it back exactly as the widget had it and never changes it.

Typical uses:

  • Where the user is: "step": "2".
  • What already happened: "approved": "true".
  • Ids found earlier: "assetId": "LT-0042".

Every value must be a string. To store a number or a list, encode it yourself, for example "ids": "4,7,9".

To change state, return a new one in your next response.

form

form holds the user's answers: a field identifier mapped to the chosen choice identifiers.

  • If the widget is a Form and form already has an answer for its field, that answer is shown as selected.
  • If the user changes the selection, the answer for that field is updated in what is sent.
  • The answer is stored by the field's identifier. Answering a new field adds an entry.
  • If the user goes back and changes a field, that entry is replaced. Other entries are untouched.
  • Answers from earlier fields stay in form, without your API returning them.

You can also return answers in form to show them as selected.

Example

Step 1 asked about accessories. Your response for step 2 may include the earlier answer in form, so it shows as selected. This is optional: the UI already holds it,

{
  "type": "form",
  "title": "Delivery",
  "value": {
    "type": "single_choice",
    "identifier": "delivery",
    "name": "How should it be delivered?",
    "choices": [
      { "identifier": "post", "name": "Post" },
      { "identifier": "pickup", "name": "Pickup" }
    ]
  },
  "form": { "accessories": { "choices": ["bag", "mouse"] } },
  "state": { "step": "2" },
  "primaryAction": { "label": "Next", "url": "/widgets/order/confirm" }
}

The user picks Pickup and presses Next. The next request contains:

{
  "form": {
    "accessories": { "choices": ["bag", "mouse"] },
    "delivery": { "choices": ["pickup"] }
  },
  "state": { "step": "2" }
}

accessories is kept by the UI. delivery is the user's new selection. state comes back as you sent it.

Going back

A reload clears everything. If the flow must survive it, store progress in your own API, keyed by the ticket and by who is reading it (identify the user with the delegate token, see How the Widget Is Requested). If it doesn't need to, store nothing, and the flow starts again.

How did we do?

Ticket Widget: Control When a Widget Refreshes

Ticket Widget: Error Responses and Debugging

Contact