Setting up Forms

No matter what conversational experience you're creating, you're inevitably going to be collecting some information about your users: this can range from products they like, what their favorite time to receive a message is, or how satisfied they are with an experience. You're probably already using user properties to store this information and create more personalized, smart experiences. However, user properties aren't great when you're attempting to store multiple instances of the same piece of information: ie a CSAT survey.

Forms allow you to group up and report on related pieces of date over time. In this example, any properties we save within this form (CSAT score, feedback, etc) will be be grouped up and reported together. So now a user can go through this CSAT survey multiple times without overwriting their previous survey.

Setting Up a Form

Create a 'formInstance' User Property

In order to set up your form, you'll need to create a user property named formInstance that will be used to signal both the start and the end of a form.

Using 'formInstance'

In the example below we are going to be creating a CSAT survey for users who received order updates via conversational AI. The first step is to set a formInstance user property on the block that will serve as the beginning of this form.

Starting a Form

In this instance we're going to set the value to SET_orderDeliveredCSAT where SET serves as the beginning of the form and orderDeliveredCSAT serves as the name of the form. You can create any form name that represents what your form is designed to capture as long as it is preceded by SET_.

Multiple Entry Points

You can use as many entry points (SET_formNAME) for a given form as are necessary: conversational AI is inherently not linear so it may make sense to begin a form in various places.

Collecting User Properties in a Form

Once a user has transitioned to a block that has the formInstance property with a value of SET_formName, any user properties collected will be added to that form until they transition to the end of the form or they reach the start of another form. In this example we'll want to save the user's response to our CSAT order delivery question as a property.

User Property Naming Convention

If you're going to be collecting CSAT, NPS, or any other property in multiple places and would like to report on each separately make sure you give them different names. Ie customerCareCSAT & orderDeliveredCSAT

Ending a Form

Similar to the start of your form, you'll want to set a user property on the block that represents the end of your form. Instead of using SET_formName you'll want to use UNSET. Also like entering a form, a form can be ended on multiple blocks.

Backfilling a Form Instance and Creating Reports

  • Get the appvar id for any of the user properties you're saving in the Form Instance flow: In CMS, go to User Properties, click on the property you're trying to measure (i.e. NPSScore) and copy the id from the very end of the url following /appvars/.
  • If you recently set up a form instance for a flow, but have been running that flow for some time and want to see past data reflected in Analytics, you'll need to run a backfill.

Backfilling a Form

  • For each appvar_id, send a POST request to:

Forms in Analytics Reports

  • var_set_events
    • All var_set_events that are part of a form instance or backfill have the appvar_id in the to_state_id field
    • event_properties field
      • will have a key of the property name (NPSScore) and the value of the user property value that was set
      • formInstance key will be:
        1) the same for all user properties that were backfilled ('backfill')
        2) different for user properties that were set during different form instances (and same for user properties that were set during the same form instance)
      • If you will need a date the user property was set, backfilled events will only have unix time as recordTime key. To be able to segment by date, you can add this inside withParams:
        const datekey = `dateadd(S, nullif(json_extract_path_text(event_properties, 'recordTime', TRUE), '')::BIGINT/1000, '1970-01-01')`;
        
  • To create a user property per form instance by user chart (ie: NPS Score+Comments by User) chart:
  • Calculating NPS: # Promoters minus # Detractors over # Respondents times 100, where the response was a number from 0-10
    • Promoters: Score of 9 or 10
    • Passives: Score of 7 or 8
    • Detractors: Score < 7

Updated 27 days ago

Setting up Forms


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.