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 data 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:
  • https://snapsmedia.io/api/appvars/backfillVarSetEvents/{{appvar_id}}
  • This will generate a var_set_event in the events table for every time the user property was set prior to the creation of the form instance. Now you will have var_set_events that are being created during the active form instance and also from the backfill

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:
    JavaScript

    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:
  • For no backfill: group var_set_events by the formInstance
  • For backfill, you will need to combine two different types of var_set_events from the mv_bot_events table, differentiated by having the formInstance value of 'backfill' vs. different values:
    1) for non-backfilled events: grouped by the form instance (potentially producing more than 1 row per user)
    - See example:
    https://github.com/SnapsApp/scripts/blob/876e105047047b7de9ace8ec4ce0c48581d89b3b/5e397f85853f1c0159bfb567/scripts/5eaaf6743e60ee71ef9c0ab3.js
    2) for backfilled events: grouped by the user's last Score and last Comment (producing a max of 1 row per user)
    - See example: https://github.com/SnapsApp/scripts/blob/eee8570111774e153cdd8cf8364e66c7f2a462e7/5a2594554301f72a76c808bd/scripts/5a30cda1987bf73841af3ff4.js
• 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