22 Instant Apps

Natural language conversations are, by their very nature, free-flowing. But they may not always be the best way for your skill to collect information from its users. For example, when entering credit card or passport details, users need to enter specific information (and enter it precisely). To help with these kinds of tasks your skill can call an instant app, which provides users with forms that you create using labels, options, check boxes, data fields, and other UI elements for easy data entry.

Get to Know an Instant App

Let's use a financial skill for the fictitious Standard Bank as an example of how a skill interacts with an instant app.

Suppose that after querying the checking account balance in the skill, the user sees an error and enters, “I want to dispute a charge”. The user receives a link which in turn opens the instant app in a web view. When the instant app opens, it’s populated with values that are passed from the skill about the disputed transaction: the date, merchant, amount, and description of the transaction.
This is an image of the starting pane of the instant app.
The instant app then provides a wizard-like experience for the user to enter information about the charge. When the user is finished entering the requested information , the instant app executes a callback to return the user from the instant app to the skill, where it displays a confirmation message detailing the disputed transaction. The confirmation message includes the reason for the dispute and the dispute number, both of which are values returned from the instant app.
This is an image of the call back message.

Video: An Introduction to Instant Apps

Check out this video to find out how you can use instant apps.

Explore the Instant App Builder

An instant app called Bank Transaction Interactive With Verify, along with other instant apps created for you, is available by clicking Instant Apps in the Digital Assistant landing page.
This is an image of the Instant Apps button.

Once you're on the instant app landing page, double click the Bank Transaction Interactive With Verify tile to open it in the Instant App Builder. Click through menus on the left side of the editor to open the panes that make up the instant app’s pages, their UI elements, the actions configured for the elements, the parameters passed between the skill and instant app, and so on.
This is an image of the instant app builder

How Do I Create an Instant App?

Here’s the basic flow for creating an instant app.
  1. To start from scratch, click New Instant App. If you’re not sure exactly where to start on your instant app, choose a template similar to the task you need the instant app to do. As you work in the template, you can customize it to your business needs.
    This is an image of the instant app landing page showing the templates for Add, Work Order, Customer Survey, and My Instant App.

  2. Configure the basic information about the Instant App —Click Instant App Info in the editor. Complete the Instant App configurations. Most importantly, define the ID. You need this value to define the id property for the System.Interactive component.

  3. Create the invitation for you user to access the instant app —ClickInvitation. Add an invite message and any graphic you'd like to use for your instant app.
  4. Build the UI—Expand Layout to access the default pane. Rename the default pane (PANE_1) to something that reflects the pane's function.

  5. Populate the pane with UI elements— Click + Add Element in the editor. Next, drag the UI element into the editor and then configure it. You set the validation on a UI element.

  6. Set the parameters sent from the skill—Click Parameters then click + Add Parameter. Enter the parameter names defined in the sourceVariableList component.

    Important:

    Be sure that the parameter names exactly match the values defined for the sourceVariableList. If they don’t do so, users will get a 500 error message.
  7. Enable the instant app to receive parameter values — Click Events and Actions. if you need to dynamically populate options lists with values, add an App Sent action.
    • Click App Sent > Add Action. Choose a JavaScript Snippet action to populate entire groups of check box or radio button options.

  8. Return users to the skill — Click Events and Actions then select a UI element, such as a button. If needed, choose a validation option. Next, click + Add Action and then choose Exit to Skill. Configure a parameter that passes the user input back to the skill. Note that because this is dynamic input, you need to enclose the parameter value in curly braces.

How Do I Integrate an Instant App with a Skill?

To integrate an instant app, you need to configure both the dialog flow and equip the instant app with actions that get input values from, and return other values to, the skill.

Calling the Instant App in the Dialog Flow

Update the dialog flow to set the parameter values and call the instant app:
  1. Declare the variables in the context section.

  2. If your dialog flow uses the System.Intent component, add an action transition to the state for the instant app.

  3. Set the parameter values that get passed to the instant app by defining one or more states that use the System.SetVariable and System.ResetVariable components.

  4. Add the state that handles the hand off to the instant app using the System.Interactive component. Set the following properties to enable the skill-instant app interaction:
    • sourceVariableList—A comma-separated list of user or context variable names.

    • variable—A variable that identifies the payload returned by the instant app’s callback.

    • id—The ID of the instant app, which you get from Settings in the Instant App Builder.

  5. After the System.Interactive state, you can add another state that references the variable property to display or set the payload values. For example, you can use the System.Output state to display the values returned from the instant app. In the following example, the text property uses an Apache FreeMarker operation that names the System.Interactive’s variable property along with the parameter set for the Exit to Skill action that’s configured in the instant app. In the following snippet, the name of this parameter is selected. In the Instant App Builder, the value for this parameter is the name of a UI widget that holds the user value ({singleLineInput_1}, for example).
     callInstantApp:
        component: "System.Interactive"
        properties:
          sourceVariableList: "list"
          variable: "instantResponse"
          id: "my_instant_app"
          prompt: "Continue to our online store."
          linkLabel: "Click me."
        transitions:
          actions: 
            cancel: "cancelInstantApp"
          next: "printChoice"
    
     printChoice:
        component: "System.Output"
        properties:
          text: "You ordered ${instantResponse.value.selected?capitalize}."
          keepTurn: false
        transitions:
          return: "done"
    Built-In String FreeMarker Operations describes formatting options for output strings.

Tip:

Add navigation to your flow to enable users to opt out of using the instant app.

Configuring the Instant App to Retrieve Parameters from the Skill and Return Values Back to the Skill

Your instant app also needs the following:
  • An App ID—Reference this in the System.Interactive ’s id property.

  • Parameters—Create parameters for the values that are passed from the skill. These parameters must match the System.Interactive’s sourceVariableList property.

  • An Exit to Skill action—You can set this action on a UI element, like a Submit button and if needed, use it to return values to the payload variable defined for the System.Interactive’s variable property.

    Tip:

    Use curly braces for dynamic content. To do so, enclose the name of the UI element that holds the user input in curly braces, for example ({singleLineInput_1}).
  • An App Sent Event—Use this event when you need to dynamically populate the instant app’s options lists, radio buttons, or check boxes with the variable values collected by the skill.

    To access the input parameters, define this event using a JavaScript Snippet action that’s instantiated by function appSent(app, chatbox, customer) {}. This function’s app argument accesses the input parameters from the skill (that is, the value defined for the System.Interactive’s sourceVariableList property), so use the app.parameters function to get the parameter value itself. For example, app.parameters.list accesses the values for the list input parameter that’s defined for the sourceVariableList property.

    To populate the a UI element with parameter values, use app.setElementOptions(ElementName, values). Note that ElementNamerefers to the value entered into the Element ID field when clicking Add Element .

Video: Calling an Instant App from Your Bot

This video steps you through the entire process of connecting your bot to an instant app.

Manage Information About the Instant App

App Settings is where you manage general information about your instant app.

Name

A name that identifies your skill in the landing page. It’s for your reference only; end users can’t see it. The name can include letters, numbers, and special characters.

ID

The instant app ID is how you reference the instant app if you need to call it from somewhere. You reference this value in the id property of the System.Interactive component, or in an API or JavaScript Snippet. When you create a new instant app, the ID is derived from the instant app name that you enter. This ID cannot contain special characters or spaces. You can edit the ID at any point, but if you do change it, you will need to update any references to the previous ID.

Icon

An icon is the image that shows up on the instant app tile on the main instant apps page. Remove unwanted icons by clicking on the red X in the top right corner. Then you can drag and drop an icon, add an icon via regular file lookup, or input a URL.

Internal Description

A short description that displays on the instant app’s tile. It’s for reference only; end users can’t see it.

Initially Active

When you create a new instant app, you can set the instant app to be Initially Active before you save it. If you set it to active, the instant app can be activated from the skill. If you do not set it to Initially Active, then you can always set it to Active from the instant app tile on the main menu. You can see which apps are inactive by the Inactive display next to the instant app name.

The Invite Message is a pre-configured message that is sent to customers inviting them to use the instant app, and it is the first thing a customer sees.  Include the {link} in the position where you want the instant app link, and do not change anything else. The message, including the link, cannot exceed 160 characters.



Lay Out an Instant App

Laying out an instant app includes selecting panes, adding elements, and identifying information such as Pane IDs with the instant app builder. Instant app layouts are highly customizable to suit your business needs.

Panes

Panes are essentially the pages of your instant app. Some scenarios require just a single pane experience, where a customer clicks into the instant app, engages, and then is taken back to the skill conversation. More complex instant apps will have multiple panes to minimize the amount of information on a single screen. Panes are flexible and allow you to optimize your customers’ experience based on the content you’re delivering

When you first click to build out the layout of your instant app, you will see a single pane as a starting point. Before jumping into adding Elements, make sure to edit Pane ID. Renaming Pane ID to describe the function or purpose of the pane will make it easier to identify when modifying your instant app in the future. Note that Pane IDs can only contain letters and numbers. No spaces or special characters are allowed.
Image shows the main panel in the Instant App Builder. The field Pane ID reads Pane 1.

Styling can also be configured on a Pane. Specify a background by either setting a background color or a background image. You can also specify a border around your Pane.

Pane Validation Options
Each pane in an instant app has two main validation options:
  1. Validate individual input Elements as they are edited as well as all when submitted—If a customer enters data that’s not valid (for example, a phone number that does not conform to the prescribed regex), then they would immediately see an error message. The instant app will also check that everything is valid before moving on to the next pane.

  2. Validate all inputs only when submitted—When you set this condition, a customer doesn’t see an error message immediately after entering data that’s not valid. In this case, the customer could continue to fill out the other fields and would not see the error message until the problematic data is submitted.


This image shows the pane validation options. The first option , “Validate individual input elements as they are edited as well as all when submitted”, is selected.

Add the messages that display under either of these conditions in the Pane Error Message field. This message appears directly above the element (typically, a button) that triggered the submission of the invalid data. Use the Validation tab for an individual element to create an additional error message that displays next to the error-causing element(s).

You can also validate a pane by writing your own JavaScript. The message included in the code is triggered when the pane is submitted. This image shows the validation pane with the JavaScript validation function check box selected.

Elements

You build the instant app’s UI by dragging widgets, called elements, into the + Add Element fields in the editor’s Layout panel. After you add the element, click it to open its editor to configure its display, style and validation options. An element’s editor includes Configure, Style, and Validation tabs for accessing these options, which vary depending on the element. For example, the editor for the Single-Line Input element includes all three tabs, but because the Image element doesn’t require validation, its editor only includes the Configure and Style tabs.

Move, Add, and Delete Elements
Here are some tips on managing and positioning elements:
  • Moving elements—To move an element, click on it and drag and drop to the desired location. Elements can be moved within a pane or across panes

  • Adding multiple elements—You can add elements in bulk to an active pane using Command + Shift. Use this shortcut as you click on the elements that you want to add. The elements get added in the order that they’re clicked.

  • Cloning Elements—If you’re using the same element multiple times across an instant app, you can clone the element by clicking the ellipsis to the right of the element name and then choosing Clone. All of the configuration, style, and validation get cloned to the new element, but any associated events and actions are not cloned

  • Delete elements—There are two ways to delete an element. When you click on an element and drag it, you will notice a Delete bar on the bottom of your screen. Drag and drop the element to the Delete bar to delete it. Or, click on the ellipsis next to the element name and click Delete.

Common Element Configurations

Many elements have some common configurations. Here are some of the common options.

Element ID

The Element ID is the name of the element. You typically reference this value (referred to as ElementName) in a JavaScript Snippet action. When you need to return the values for a UI widget back to your skill, you reference the ElementName as a parameter value and enclose it in curly braces.
This is an image of the element ID field. The field contains the words “button one”.

Initially Visible

You can make each element visible or invisible when the instant app pane loads. If it’s invisible when loaded, then a user would not see it unless you create an action to make it visible.

Initially Enabled

You can make an element enabled or disabled when the instant app pane loads. If it’s not enabled when loaded, then a user could not input anything into or affect the element. If you would like a user to be able to interact with it, then you would need to set up an action to enable the element.

Label

Generally, a label is what you would see above an element that describes what it is or its function. A few elements have unique label behavior which are called out in the specific element. Labels can use HTML or can be dynamically updated when you reference a parameter using curly brace notation.

Display Label Inline

For Elements where the label is listed above it, you can select Display label inline, to make the label appear on the same line as the element.

Placeholder

You will see a configuration for placeholder in a few different elements, primarily the text input elements. Any text configured here will show in gray, inside the text input box. Once a customer inputs any text into the field, the placeholder will disappear. A common use for placeholders is to configure an empty label, but be sure to set a label/description as the placeholder.


This image shows the configure fields on the left. On the right is an image of a cell phone screen with the preview option selected and an empty field showing as the preview.

Tool Tip

Tool tips can be used to show help text. The tool tip will show when users interact with the element.

Styles

Styles are fairly similar across elements, with only a few variations.

Font

Text fonts and features within elements can be adjusted in these ways:
  • Size: In Pixels

  • Weight: Normal, Bold, Light

  • Style: Normal, Italic, Oblique

  • Alignment: Left, Center, Right, Justified

Layout

The Layout section of the Style Tab varies between elements. Input for the following options can be given in pixels or as a percent

  • Element Width: This is the width of the entire element. Different elements have different defaults. For example, a label defaults to 100%. Setting the element width to a smaller number allows for more than one element to show up on the same line.

  • Top Margin: The distance between the previous element and the element you are editing.

  • Left Margin: The space between the left edge of the instant app and where the element begins.

  • Right Margin: The space between the right edge of the instant app and where the element ends.

  • Bottom Margin: The distance between the element you are editing and the element which follows.

The Inner Dimensions control the used portion of the width of an element, given the constraints you’ve created on element width, left and right margins, and the height of the element. For example, if you set the element width of a button to 75 percent and then set the Inner Dimension width to 100 percent, the button will expand to fill the entire 75 percent. As another example, if you set the element width of a Label to be 50 percent the left margin to be 20 px, and the Inner Dimension width to be 50 percent it would result in the label starting 20 px to the right, and only filling up half of the text box, or 25 percent of the width of the instant app since the element width had already been set to 50 percent (50 percent of 50 percent = 25 percent).

Foreground Color and Background Color

The Foreground Color generally controls the text in an element and the Background Color generally controls the area of the element behind the text. They can differ somewhat between elements because of the variety of element types, so specifics are called out in each element. However, for any of the elements that have buttons embedded in them (like Upload, Location, Signature), the button color can’t be changed.

Border

For most elements, you can control whether there is a border around the element or not, and how the border looks. You can adjust the width, whether it is solid, dotted, or dashed, the shape of the corners, and the color.  In some element types, for example Images, if you increase the corners sufficiently and adjust the Layout, you can create oval and round shapes.

Element Types

The specific configuration, style, and validation options are listed here:

Text Inputs

Single Line Input

Use the Single Line element for any text comprised of letters, numbers, and special characters. This element is commonly used to collect a user name. You can use the following validation options for this element:
  • Required—You need to add an error message with this option.

  • Minimum and Maximum Characters—These elements have a maximum length of 256 characters.

  • Matches Regular Expression—Choose this if the input needs to match the pattern described by a regular expression (regex). You can remind users how to enter the input correctly using the Failure Message field.

  • JavaScript Validation Function—Use this if the field requires complex validation and needs to leverage the validator object .

Multi-line Input

Use a Multi-line Input element for lengthier text. You can specify how many rows are shown in the display of this element. You can use the following validation options for this element:
  • Required—You need to add a error message with this option.

  • Minimum and Maximum Characters—Multi-line Input elements have a maximum input character length of 1000 characters

  • Matches Regular Expression—Choose this if the input needs to match the pattern described by a regular expression. You can remind users how to enter the input correctly using the Failure Message field.

  • JavaScript Validation Function—Use this if the field requires complex validation and needs to leverage the validator object.

Email

Use this element to capture an email address. To avoid an error message, users need to enter @ and a completed domain. You can use the following validation options for this element:
  • Required—You need to add a error message with this option.

  • Matches Regular Expression—Choose this option if the input needs to match the pattern described by a regular expression . You can remind users how to enter the input correctly using the Failure Message field.

  • JavaScript Validation Function—Use this if the field requires complex validation and needs to leverage the validator object.

Number

Use this element to collect integers, currency values, percentages, or decimals. Phone numbers have their own element, described below. Some things to keep in mind when configuring this field:
  • The Number Type option affects how the element displays by enforcing he input type (currency, integer, percent, decimal) on the filed.

  • The Thousand Separator option enables you to include a common separator for the thousands’ place.

You can use the following validation options for this element:
  • Required—You need to add an error message with this option.

  • Matches Regular Expression—Choose this option if the input needs to match the pattern described by a regular expression. You can remind users how to enter the input correctly using the Failure Message field.

  • JavaScript Validation Function—Use this if the field requires complex validation and needs to leverage the validator object.


This image shows the Number Type field open. The field has four options available: integer, currency, percent, and decimal. Currency is selected.

Phone

This element provides a stylized input field for phone numbers. Customers can use the drop-down menu to set the default country code before entering their phone number. You can use the following validation options for this element:
  • Required—You need to add a error message with this option.

  • Matches Regular Expression—Choose this if the input needs to match the pattern described by a regular expression. You can remind users how to enter the input correctly using the Failure Message field.

  • JavaScript Validation Function—Use this if the field requires complex validation and needs to leverage the validator object.

.

Website Address

Use this element when you need to collect website information from your customers. Valid user input begins with the protocol (http:// or https://). If user don’t enter this, they’ll receive a a malformed URL error message. You can use the following validation options for this element:
  • Required—You need to add an error message with this option.

  • Matches Regular Expression—Choose this if the input needs to match the pattern described by a regular expression. You can remind users how to enter the input correctly using the Failure Message field.

  • JavaScript Validation Function—Use this if the field requires complex validation and needs to leverage the validator object.

.

Rich Text

The Rich Text Element is similar to the Multi-Line Input element, but it allows customers to add HTML formatting inside the text field. Below the element are three icons: edit, preview, and help.
This image shows the rich text element with the edit, eye, and question mark icons on the bottom
The help icon displays supported formats and samples. These formats include:

  • <br /> line break

  • <b>bold text</b>

  • <i>italic text</i>

  • <u>underlined text</u>

  • <center>centered text</center>

  • <h1>header text</h1>

You can use the following validation options for this element:
  • Required—You need to add an error message with this option.

  • Minimum and Maximum Characters—Multi-line Input elements have a maximum input character length of 1000 characters

  • Matches Regular Expression—Choose this if the input needs to match the pattern described by a regular expression. You can remind users how to enter the input correctly using the Failure Message field.

  • JavaScript Validation Function—Use this if the field requires complex validation and needs to leverage the validator object.

Choice Inputs

Checkbox

The Checkbox element is typically used for an acknowledgement or confirmation. You can add multiple checkbox elements, or use a Picklist element. You can use the Required validation option for this input. If you use this option, you must add an error message.

Radio Buttons

Use radio buttons when you need your users to pick from a list of options. Your instant app can have a minimum of two radio buttons. You can associate actions with these options.


This image shows the Radio Buttons options menu. The Radio button label field in the first ine is set to option 1. The value field is set to value1. In the second row, the radio button label is set to option 2 and the value is set to value 2.

If you select Load Options with Action for either the Checkbox or Radio Button elements, you need to specify the values by either adding a JavaScript Snippet action in the App Sent event, or by retrieving the values from a call to an external web API. In either case, the values must be expressed as a JSON payload with the following structure:

var obj = [
{"label": "Label One", "value": "value1" }

,
{"label": "Label Two", "value": "value2" }

,
{"label": "Label three", "value": "value3"}

];
//radioButtons_1 is the name of my radio button UI component in the instant app.
//app is an argument that gets passed in by the instant app. It allows you to access
//the setElementOptions function

app.setElementOptions('radioButtons_1',obj);

You can use the Required validation option for this input. If you use this option, you must add an error message.

Picklist

A Picklist element is used when you want a user to choose multiple options. You can configure as many items in the Picklist as needed. If you select Load Options with Action, you need to specify the values by either adding a JavaScript Snippet action in the App Sent event, or by retrieving the values from a call to an external web API. In either case, the values must be expressed as a JSON object with the following structure:

{"options": [
{ "label": "Label One", "value": "value1" }, 
{ "label": "Label Two", "value": "value2" },
{ "label": "Label three", "value": "value3" } 
]} 

Select Menu

Select Menu elements allow users to choose from a drop-down menu. In addition to setting the options for the menu, you also have the ability to set a label inside of the Select Menu box.
This image shows the select menu. From top to bottom, the label inside the select menu field is set to Select. The select options labels are set to option 1 with a value of value 1, and option 2 with a value of value 2.

If you select Load Options with Action, you need to specify the values by either adding a JavaScript Snippet action in the App Sent event, or by retrieving the values from a call to an external web API. In either case, the values must be expressed as a JSON object with the following structure:
{"options": [ 
{ "label": "Label One", "value": "value1" }, 
{ "label": "Label Two", "value": "value2" }, 
{ "label": "Label three", "value": "value3" } 
]}

You can use the Required validation option for this input. If you use this option, you must add an error message.

Special Inputs

Buttons

You typically add buttons at the end of a pane, where they can be linked with either an event or an action, or both. You can add buttons to help a user navigate within an instant app, or exit from an instant app. You can style your button and adjust button size in style layout. The inner dimension of a button should be set to 100 percent if you want the button to be the width of the device screen.
This image shows the button styling menu. At the top of the menu, the element width box is set to 100 percent.

Upload Photo or File

The Upload Photo or File element allows users to upload an image or a file into the instant app. Here is what the choices mean:
  • Upload Label— This text appears above the Waiting for Upload message.

  • Button Text—The upload text that appears on the button.  

  • Show Filename— Select this option to allow users to see the name of their uploaded file.

  • File Size Limit— You can set the limit, in bytes, of the file size. The default is 10000000 (10MB).

  • Show a Preview of the Uploaded Image—Allows users to see their images after they’ve uploaded them. You can’t view the actual image in either the Test or Preview modes. A placeholder image appears instead.

  • Preview Height Max and Preview Width Max— Set the size of the preview in pixels. The default is height 200 px, width 300 px .

  • The size, weight, and style of the upload label, the Waiting for Upload message, and the button text are controlled by the size, weight, and style in the style tab. The Foreground Color controls the color of the upload label text and the Waiting for Upload message. You can’t change the color of the upload button itself, or its display text. The Background Color controls the area of the upload element that’s behind the upload label, the Waiting for Upload message, and the button.

  • You can choose the Required validation option for this element.

Date

The Date element lets users easily pick a date from a dropdown calendar. There’s no formatting for this element because users aren’t entering any values manually.
  • Placeholder—Placeholder text that appears in the area that displays a selected date. This text gets replaced with the date value.

  • Get Time—Enables the user to select a time as well as the date.

  • Minimum Date and Maximum Date–When these are set, a user will not be permitted to select a date earlier than the Minimum or later than the Maximum. If you set these values manually, use the MM/DD/YYYY format.

  • The size, alignment, weight, and style of the placeholder text is controlled on the Style Tab. The Placeholder text color cannot be adjusted. The width and margins of the Date Element can be adjusted using pixels or percentage, but if you make the width too small, the user will not be able to see the full date and time.  The area of the Date element behind the placeholder text is controlled by the background color.

  • You can choose the Required validation option for this element, or you can write a JavaScript snippet that validates this element when you choose JavaScript Validation Function.

Signature

The Signature element allows you to capture the user’s signature. The user can sign and then clear or confirm their signature using the element’s Clear and Clear and Confirm buttons. Both buttons are initially disabled, but become enabled after the user signs. If the user clears the signature, then both buttons will become disabled again. Here are some things to keep in mind about this element:

  • You can change the display text for the Confirm button but not the Clear button.

  • You can style signature box using a background color and use a foreground color to style the signature itself.

  • You can choose the Required validation option for this element.

Star Rating

The Star Rating element allows you collect user ratings. Keep the following in mind when using this element:

  • You add any number of stars that your rating system requires.

  • If stars aren’t suitable icons, then you use a Font Awesome icon instead. To access these icons, click Font Awesome Icons.

  • You can set icons at either end of the star icon. By default, these icons represent low and high ratings using frowny and smiley faces, but you can replace these with Font Awesome icons, or you can remove them altogether.

  • From a style perspective, the font size controls the size of the Font Awesome icon, foreground color controls the color of the Font Awesome icon, and the background color controls the color behind the icons.

  • You can choose the Required validation option for this element.

Slider

The Slider element allows a user to move a selector along a numeric spectrum and pick a number within the range. You can set the minimum value and the maximum value using the Min Value and Max Value fields, respectively; both must be integers and the maximum value must be equal or greater than the minimum value. You can increment the amount of the slide by entering a number in the Stepfield. For example, if your Min Value is set to 0, your Max Value to 10, and your Step value to 2, then as the user moves the slider along, it would increase from 2 to 4 to 6, and continuing on.

To change the right, left, top, and bottom margins, you can enter the value as a percentage or in number of pixels. The area behind the Slider can be adjusted by using the Background Color.

The Slider element doesn’t require validation.

Location

The Location element can be used to capture the location of a user. In order for the Location element to be set up, you need to have a Google Maps API Key. For it to work with a user, their device needs to support location services and be enabled.
  • The Location element can be used to capture the location of a user. In order for the Location element to be set up, you need to have a Google Maps API Key. For it to work with a user, their device needs to support location services and be enabled.

  • The Location element can be used to capture the location of a user. To set up the Location element, you need to have a Google Maps API Key. For it to work with a user, their device needs to support location services and must be enabled.

  • Show Map: If enabled and the user’s location is received, the user will see a map of their location.
    This image shows a map indicating location services are supported and a box with a message that location services are not supported.

  • Google Maps API Key—Paste an active Google Maps API key. You can get this key from Google Maps Platform.

  • Destination—A target destination that’s rendered in the map relative to the user’s current location. After the user’s location is discovered, the map renders the route.
    This image shows a map with directions to the Space Needle in Seattle, Washington

  • Font Size, Foreground Color, Weight, and Style control the size, color, weight, and style of the label text on the button; Background Color controls the color of the button itself. To change the right, left, top, and bottom margins, you can enter the value as a percentage , for example 10%, or in number of pixels, for example, 20px.

  • You can choose the Required validation option for this element (and provide an error message if you choose this option).

Barcode Entry

The Barcode element allows a user to take a picture of a barcode. From that image, the barcode numbers are extracted and displayed. A Barcode Not Detected message alerts users when the barcode is undetected in the uploaded image. After users upload an image, a Clear button appears, giving them the option to remove the current image. For example, this option lets them remove unreadable images. Note that you can’t view the actual barcode image in the Preview and Test modes. A placeholder image displays instead. Here are some configuration, style, and validation options for this element:
  • Instructions— The prompt that displays within the barcode box directly above the Select Image button. By default, its Take a picture of the barcode, but you can change this text. However, you can’t change the button’s Select Image display text, nor can you change the or Drag and Drop text that appears directly beneath this button.

  • Allow Manual Barcode Entry —Selecting this option enables users to enter barcode number manually if they don’t (or can’t) upload a photo.

  • Show Preview Image— Displays the the uploaded image.

  • The Foreground Color controls the instructions text and or Drag and Drop text. The Background Color and Border control the background color and the border of the barcode box where the instruction text, Select Image button and or Drag and Drop text are.

  • You can use the following validation options for this element:
    • Required—You need to add a error message with this option.

    • Matches Regular Expression—Choose this if the input needs to match the pattern described by a regular expression . You can remind users how to enter the input correctly using the Failure Message field.

    • JavaScript Validation Function—Use this if the field requires complex validation and needs to leverage the validator object.

Images and Layout

Image

You can upload a static image to your instant app. Do this by dragging and dropping any image on your desktop, or by entering an image URL to upload. Styling is limited on images and is restricted to layout, where you can adjust dimensions and border color.

Image Gallery

An Image Gallery allows users to see a set of images in a carousel. You can add images by drag and drop or by looking up a file. You can control the way the carousel looks and interacts via a series of checkboxes, for example, Show Index, and Show Play Button; see image below for a complete set. You can also set the rate at which the images advance (in milliseconds) by setting the Play Interval.  There are no style or validation options with the Image Gallery.
This image shows an image of grass with three thumbnail pictures below the main picture.

Divider

The Divider Element creates a line in the instant app. Through the Style Tab, you can control the height of the bar (in pixels only) as well as its color.  The divider is a fixed length, which is the full width of the instant app. There are no validation options.

Content

Label / Text

The Label element allows you to add static text anywhere within your instant app. This element is often used to create headers for sections or to write lines of text between other elements. You can format this element using markdown.

HTML

The HTML element lets you create your own content using the following HTML tags:

  • <div></div>

  • <span></span>

  • <center></center>

  • <u></u>

  • <b></b>

  • <i></i>

  • <a href="link"></a>

  • <br>

You can add Font Awesome icons, for example, for star ratings (<i class="fa fa-star"></i> ). The Style tab options don’t override the alignment or fonts defined in the HTML code. For example, you change the font weight of Hello!, but not How are you? in the following snippet. Likewise, you can’t change the font weight for How are you?, but you can for Hello!.

<center> Hello !</center>
<br>
<b> How are you? </b>
Note that if you click out of the HTML box, you can see your text appear in the preview.

Social Buttons

The Social Buttons element adds Facebook, Twitter, LinkedIn, and Instagram icons to your instant apps. Users click these icons to navigate to the social network.

You provide the URLs for these providers in the Configure tab. You can control which icons appear by adding the respective URL. For example, if you do not want to have an icon for Instagram show up on your instant app, simply leave the Instagram input field blank.

You set the separate styles on the background circle and the actual icon The icon’s size and color are controlled by the font size and foreground color. The color of the circle around the icon is controlled by the background color. A circle is the default shape because the inner dimensions are set to equal numbers (50px, 50px). If those are not equal, it will result in an oval. Also, the border of the circle has rounded corners set to 50%. If that is changed, you create shapes other than a circle, depending on the percentage set and on the inner dimensions.

YouTube

The YouTube element will show the user an image link to a YouTube video. When the user clicks on a video, it plays within the instant app itself, so the user remains in the instant app.
  • Label— The label displays text above the image link to the video

  • Video URL—In the video URL field, enter URL to the YouTube content.

  • Show URL—If you enable show URL, the video’s URL displays below the image link.

  • For the style, you can configure the top, bottom, right, and left margins of the image of the video using pixels or percentage.

Embedded Website

The Embedded Website Element allows you to iFrame a website to your instant app with a fixed height and width. You might do this, for example,  if you want to be able to process a payment for a user. You would input the URL in the website URL and if you want the URL to be visible (it renders above the iFrame), you select Display URL. For privacy or other reasons, uncheck Show the Website to Sender if the user is the only one who should be able to see the website. If the website you are embedding has data that you want to pass back to the instant app, you should select Append Callback URL.  Following our example of processing a payment, if a payment succeeds, you may want the user to have one experience, and if it fails, you may want the user to have a different experience.  In order to set element values and drive different instant app behaviors, select Append Callback URL. These instructions detail how callback URLs work:

  • You can set the fixed height of the iFramed website by adjusting the inner dimension height in pixels, and the width by the left margin and right margin (in pixels or percentage).

  • There are no validations for the embedded website element.

PDF Viewer

The PDF Viewer Element allows your user to read through a PDF within the instant app. You can provide the file via drag and drop or file upload, and also set the page number you want displayed first. The user can navigate to the document using the next and previous buttons. However, these buttons are not configurable.

  • You can adjust the size of the PDF display, but if you input an inner dimension greater than 100%, you risk not displaying parts of the file, because there is no horizontal scroll bar. The default inner dimension is 90%.

  • There is no validation for the PDF viewer.

Chart

The Chart Element allows you to create four different chart types (bar, pie, line, and scatter chart) that render in your user’s instant app. For each, you can manually input data in the chart element UI or dynamically pull in data from an external source using JavaScript snippets or parameters. If you do use JavaScript or parameters, those  override any static values you have entered.

  • Single series only is permitted and each chart type has a specific data format and maximum number of recommended data points.

  • When you first look at the chart element, each chart type is pre-populated with static values. This allows you to switch between the different chart types to see how a chart renders. If you want to use JavaScript or parameters to create the chart, that data does not render a chart in preview or test mode. To see how your chart will look with dynamic data, configure and style it with static data and then uncheck Enter static values manually.  If you change the static values of a bar, pie, or line chart, the changed values are maintained if you switch between those chart types. Scatter charts have a different data input format; any changes to the static values of bar, pie, or line charts are not preserved if you change to a scatter chart.  

Bar Chart

  • Bar chart values must be entered as: Label,Value.  Labels cannot contain a comma. Values are numbers that contain "+", "-", and ".", but no commas, spaces, or other special characters.

  • Bar charts support a maximum of 40 data values, but render best with 20 or fewer. The colors of the bars can be set on the style tab using the five color palette options.

  • Data labels: You can choose to whether to show or hide data labels.  If you show them, the number value for each bar shows on the graph. Via the style tab, you can adjust the label placement of the data label up or down in pixels, and you can control the label color with the label fill color.

  • The chart title, horizontal (x) axis title, and vertical (y) axis title are set on the configuration tab and their size, weight, and color are controlled on the style tab via size, weight, and chart and axis title color. Their style is the same; you cannot control them separately.

  • The labels default to horizontal alignment along the horizontal (x) axis. To make them angled and permit more labels, use the style tab’s horizontal axis label angle. The angle can be entered as a positive or negative value:
    The image shows the horizontal axis label angle set to negative 45 and positive 45

  • By default, the vertical (y) axis minimum and maximum will be inferred from the data. if you want to set them yourself, you can uncheck Infer from Data and enter your own minimum and maximum values. These values can be positive or negative.

  • You can toggle to show or hide the legend using the Display Chart Legend checkbox.

Line Chart

  • Line chart values must be entered as: Label, Value.  Labels cannot contain commas. Values are numbers that can contain "+", "-", and ".", but no commas, spaces, or other special characters are accepted.

  • Line charts support a maximum of 40 data values, but render best with 20 or fewer. The color of the line can be set on the style tab using the data color option.

  • Data labels: You can choose to show or hide data labels on your chart. If you show them, you see the number value for each point on the graph.  Via the style tab, you can adjust the label placement of the data label in pixels, and you can control the label color with Label Fill Color.

  • The chart title, horizontal (x) axis title, and vertical (y) axis title can be set on the configuration tab and their size, weight, and color are controlled on the style tab via size, weight, and the chart and axis title color options. The title style is the same; you cannot control title styles separately.

  • the labels default to a horizontal display along the horizontal (x) axis. To make them angled and permit more labels, use the style tab’s horizontal axis label angle. As in the bar chart, the angle can be entered as a positive or negative value.

  • By default, the vertical (y) axis minimum and maximum will be inferred from the data provided. If you want to set them yourself, uncheck Infer from Data and enter your own minimum and maximum values. These can be positive or negative values.

Scatter Chart

  • Scatter chart values must be entered as: xValue,yValue.  Values are numbers that can contain "+", "-", and ".", but no commas, spaces, or other special characters.

  • Scatter charts support a maximum of 200 data value pairs, but render best with 100 or fewer. The color and size of the points can be set on the style tab using the data color and scatter size options.

  • Data labels: You can choose to show or hide data labels on your chart. If you show them, the Y-value for each point shows on the graph.  Via the style tab, you can adjust the label placement of the data label up or down, and you can control the label color with the label fill color.

  • The chart title, horizontal (x) axis title, and vertical (y) axis title are set on the configuration tab and their size, weight, and color are controlled on the style tab via size, weight, and chart and axis title color. Their style is the same; you cannot control them separately.

  • The labels themselves default to horizontal placement along the horizontal (x) axis. To make them angled and permit more labels, use the style tab’s horizontal axis label angle. As in the bar chart, the angle can be a positive or negative value.

  • By default, the vertical (y) axis min and max and the horizontal (x) axis min and max are inferred from the data provided. If you want to set them yourself, you can uncheck Infer from Data and enter your own minimum and maximum values. These can be positive or negative values.

Pie Chart

  • Pie chart values must be entered as: Label,Value.  Labels cannot contain a comma. Values are numbers that can contain "+", "-", and ".", but no commas, spaces, or other special characters are allowed.

  • Pie charts support a maximum of 20 data values, but render best with 10 or fewer. The colors of the chart components can be set on the Style Tab using the five Color Palette options.  The Style Tab also allows you to create a donut chart by adjusting the inner radius and add padding between the slices by using Pad Angle. By default, the pie chart will be 360 degrees. However, you can adjust these angles using the start angle and end angle by entering the desired degrees (positive or negative).

  • Data labels: You can choose to show or hide data labels on the pie chart slice. If you show them, you can select any combination of the value itself (the value part of the Label, Value), the percent that the value represents of the whole, and/or the slice name (the value part of the Label, Value).  On the configuration tab, you can adjust the data label placement, moving it in or out from the center of the pie.  Via the style tab, you can control the label color with the label fill color.

  • The chart title is set on the configuration tab and its size, weight, and color are controlled on the style tab via size, weight, and chart and axis title color.  

  • You can toggle the show or hide the legend using the Display chart legend checkbox.

Clear Element Errors
Use the validator object to set and clear element errors for complex validation scenarios. For example:
if (element.value == "Phil") {
    validator.displayElementError("input", "Can't be Phil");
} else {
   validator.clearElementError("input"); 
As shown in this snippet, the object surfaces two functions:
  • validator.displayElementError(<ElementId>,<errorMsg>

    Note:

    If the snippet does not call displayElementError during execution, then that element is considered valid.
  • validator.clearElementError(<ElementId>);

You can define validator objects from the Validation tab when you select the Execute JavaScript Validation option for an input element.
This is an image of the JavaScript Validation Function.

Make the Instant App Dynamic with Events and Actions

In the Events and Actions section for an instant app, you specify actions that will occur when the events trigger. For example, when the customer clicks a radio button, the instant app triggers the event associated with the radio button’s changed event. Or, when the instant app is sent to the customer, the App Sent event is triggered. This event might be used to set up the initial element values, hit an external web API to collect data, or make certain elements invisible or disabled.

Events with associated actions are displayed with a green dot in the upper right corner. Events without any associated actions will not have a dot. For example, in the following illustration, the input element firstNameInput has configured actions, while the shippingOption radio button element does not.
This is an image of event action tiles.

App Events

This is an image of the App Event options.
  • App Sent Event—This event and any associated actions are fired the very first time the instant app is sent to the recipient (a customer). Typically, you use this event for disabling or hiding elements, calling an external web API to retrieve data that is used in the instant app, and for instantiating input elements with their initial values.

  • Customer Connected Event—This event and any associated actions are fired every time the customer opens the instant app. Most often, you can use this event to refresh data from an external web source, ensure consistency and validity of the various values, and to reset the active pane.

  • Customer Disconnected Event—This event and any associated actions are fired when the recipient disconnects from the app. In general, you would use this event is to pipe partially completed data to an external web source or to the skill.

  • App Locked and Unlocked Events—This event and any associated actions are fired when the instant app is locked or unlocked. The instant app can be locked or unlocked using actions, a JavaScript snippet, or by a manual action by the sender.

  • Input Value Changed and Button Pressed Events—When instant Apps have input or button elements, an event is automatically created for that element. An element’s input events are arranged by pane. For example, the following illustration shows the events that were created for two separate panes. On the first pane (PANE_1 Events), there is an event for the single line input element named firstNameInput. This element has a green dot, which indicates that actions have been configured for it. On the second pane (PANE_2 Events), there are two events: one for the descriptionInput , a multi-line Input element and another for the submitButton Button Press event.

    The Choice elements (Radio Buttons, Checkbox, Pick List, Select Menu, Button List) support Conditional Action Lists. For these events, you can build action lists that execute when a specific condition is met. For example, the following illustration shows a radio button with Conditional Action Lists. The conditions are tested and then executed sequentially. One of the options for the Condition is value changes. By selecting this option, you enable the actions to fire whenever the value changes for the element.This is an image of configuring the conditional action lists with the Action: Make Elements Visible panel open and the Action: Enable Elements panel open.

    You can delete a condition by clicking the X icon in the upper right corner associated with the condition. Deleting a condition will delete any and all associated actions.

App Actions

Actions can be configured for each event. These actions can modify the state of the app, for example, by setting an element value, showing or hiding elements or activating a pane. You can also actions to call external web APIs or to execute JavaScript snippets.

For actions that require an element to operate on (for instance, the action), you specify the element by dragging and dropping them from the Layout section.

You can create actions using the Instant App Builder, or specify them programmatically and execute them as a JavaScript Snippet.
This is an image of the Actions options.

Event Action JavaScript Function Signature
Computation JavaScript Snippet N/A
Element Operations Set Element Value app.setElementValue(ElementId, value)
N/A Make Elements Visible app.showElements(Elements)
N/A Make Elements Visible app.hideElements(Elements)
N/A Enable Elements app.enableElements(Elements)
N/A Disable Elements app.disableElements(Elements)
N/A Toggle Visibility app.toggleVisibility(Elements)
N/A Toggle Enabled app.toggleEnabled(Elements)
N/A Set Element Label app.setElementLabel(ElementId, textOrHTML)
N/A Set Element Properties app.setElementProperties(elementId, properties)
External Data Call External Web API chatbox.callExternalWebAPI(dataKey, eventName, method, URL) and other variants.
Pane Operations Activate and Show Pane app.activatePane(PaneName)
N/A Reset Elements app.resetElements(ElementName) and app.resetElements(PaneName)
Interaction Play Sound app.playSound(soundNameOrURL, volume)
N/A Show Alert Dialog app.showAlertDialog(dialogTextOrHTML)
N/A Focus Element app.focusElement(ElementName)
N/A Open Website chatbox.openWebsite(url, dialogMessage)
N/A Open Handset SMS chatbox.openHandsetSMS(message, phoneNumber, dialogMessage)
Audit/Console Set App Status app.setAppStatus(statusString)
N/A Post Audit Trail app.postAuditTrail(string);
App Lifecycle Lock App app.lock()
N/A Unlock App app.unlock()
N/A Launch Another Instant App chatbox.launchInstantApp(schemaId, [params])
N/A Exit to Skill app.exitToBot({”name” :”parameter1”, ”value”: ”value1”})
JavaScript Snippet

This action broadens your options for configuration and error checking. You can also use it to create dynamic customer experiences. Note that all code in an Instant App is executed on the server.This is an image of the JavaScript field. The field is empty.

Each JavaScript Snippet is instantiated with a function signature.
  • Button Press Events (for Button Elements)—function buttonPressed(app, chatbox, customer, element) {}

  • Value Changed Events (for Input Elements)—function valueChanged(app,chatbox, customer, element, oldValue, newValue) {}

  • App Sent Event—function appSent(app, chatbox, customer) {}

  • Customer Connected Event—function customerConneted(app, chatbox, customer, count) {}

  • Customer Disconnected Event—function customerDisconnected(app, chatbox, customer) {}

  • App Locked Event—function appLocked(app,chatbox,customer) {}

  • App Unlocked Event—function appUnlocked(app.chatbox.customer) {}

  • Input Validation Event (on an Input Element’s Validation tab)—function validateElement(appData, chatboxData, customerData, Element, validator) {}

When the function is called on the server, function parameters are instantiated with objects that can be accessed and used along with functions that perform actions that are the equivalent to the actions that you configure with the Instant App Builder.
Function Parameters Description
app.appId The unique identifier for this instance
app.schemaId The schema number for this Instant App
app.createdTimestamp The number of milliseconds since 1/1 1970
app.status A string denoting the app’s current state as set by app.setAppStatus(str).
app.locked A boolean indicating if app is locked/unlocked
app.activePane A string indicating name of the current Pane
app.tags  
app.parameters A key-value list of parameters passed to the Instant App at launch
App.Elements
[
       {
           id
           type
           visible
           enabled
           label
           properties
           value
      }
  ]
A list of elements and all their associated information.
  • id—String indicating Element ID or name

  • type—Element Type (button, chart, etc.)

  • visible—Boolean indicating current visibility

  • enabled—Boolean indicating current enablement

  • label—String indicating current label

  • properties—Element properties (type varies by Element)

  • value—Element value (type varies by Element)

customer.customerId A unique customer ID for current customer
customer.name The customer name, if known

JavaScript Snippet Execution

  • Limited Run time and Length—JavaScript Snippets are limited to a total server run time of 1s. If your snippet exceeds that time, an error will be posted and the snippet will fail to execute. Snippets are limited to 10000 characters in total length.

  • External Resources—The only way to access external resources is to use the app.callExternalWebAPI() function, which executes asychronously and returns data to a named callback event for further processing.

  • Asynchronous, Server-side Execution—The code that is executed on the server-side. No client side injection is possible and each snippet is sandboxed to avoid data integrity issues. Snippets execute asynchronously; blocking operations are not allowed or supported.

  • Actions Performed Post-Execution—Values that are changed through a function call are not immediately reflected in the objects that were passed to the function. For instance, calling app.hideElements(“input”) will not affect the value of app.elements.input.visible within the scope of the function. For example:
    print(app.elements.input.visible);
    app.hideElements("input");
    print("After hiding: " + app.elements.input.visible);
    
    The following illustration shows how the Console reflects this action, with the visibility remaining unchanged. See Test Mode.
    This is an image of the JavaScript snippet running in the Console window.
Commonly Used JavaScript Snippets

Here are some common JavaScript snippets and guidelines.

Change the Value of an Element

function valueChanged(app, chatbox, customer, element, oldValue, newValue) {
 
  if (newValue) {
    var capitalized = newValue[0].toUpperCase() + newValue.slice(1);
    app.setElementValue(element.id, capitalized);
  }
}

Change the Behavior of the Instant App Based on a Selection of a Radio Button or Select Element

function valueChanged(app, chatbox, customer, element, oldValue, newValue) {
  switch(newValue) {
     case "shippingIssue":
        app.showElements("description");
        app.hideElements("starRating");
        break;
     case "return":
        app.showElements("starRating");
        app.hideElements("description");
        break;
     case "changeAddress":
        app.activatePane("changeAddressPane");
        break;
  }
}

Loading Values for Groups of Radio Buttons, Picklists, and Checkboxes

To populate these UI elements, you need to define a payload.

...
var obj = [
{"label": "Label One", "value": "value1" }

,
{"label": "Label Two", "value": "value2" }

,
{"label": "Label three", "value": "value3"}

];

//radioButtons_1 is the name of my radio button UI component in the instant app.
//app is an argument that gets passed in by the instant app. It allows you to access
//the setElementOptions function

app.setElementOptions('radioButtons_1',obj);
...
Set Element Value
This action sets the value of an input element. To configure this action, drag and drop the element and then specify a value. You can define this as a static value, but you can access other element values or parameters using brace notation. For example:
  • The following illustration shows setting the fullName element to a static value.This is an illustration of the Set Element Value

  • In this illustration, the fullName element is set to the value of the {firstName} and {lastName} values.
    This is an illustration of the Set Element Value configuration.

  • This illustration shows setting value of Picklist element to check options corresponding to value1 and value2.
    This is an illustration of the Set Element Value configuration.

JavaScript Action

app.setElementValue(“ElementId”, value); 

Important:

You’ll get an error if you use setElementValue to change the label or other properties of an element.
Make Elements Visible

This action displays one or more hidden elements.
This is an image of the Make Elements Visible configuration.

JavaScript Action

app.showElements("ElementName"); // single element
app.showElements("ElementName", "ElementName2"); // comma-separated Elements
app.showElements(["ElementName", "ElementName2"]); // list of Elements
Make Elements Invisible

This action hides one or more hidden elements.
This is an image of the Make Elements Invisible configuration

JavaScript Action

app.hideElements("ElementName"); // single element
app.hideElements("ElementName", "ElementName2"); // comma-separated elements
app.hideElements(["ElementName", "ElementName2"]); // list of elements
Enable Elements

This action enables the input of the elements that you drag and drop from the Layout category. The elements enabled by this action still respect the Element Usability setting, meaning that the element remains disabled when you’ve enabled an element for a target that can’t use it. See Common Element Configurations.

JavaScript Action

app.enableElements("ElementName"); // single element
app.enableElements("ElementName", "ElementName2"); // comma-separated elements
app.enableElements(["ElementName", "ElementName2"]); // list of elements
Disable Elements

Use this action to disable input for the elements that you drag and drop from the Layout category. When you disable an element, it’s grayed out and in this state, can’t accept a customer’s input or manual updates.

JavaScript Action

app.disableElements("ElementName"); // single element
app.disableElements("ElementName", "ElementName2"); // comma-separated elements
app.disableElements(["ElementName", "ElementName2"]); // list of elements
Toggle Visibility

This action toggles the visibility for the elements that you drag and drop from the Layout category. If an element is invisible, it will become visible (and vice versa). 

JavaScript Action

app.toggleVisibility("ElementName"); // single element
app.toggleVisibility("ElementName", "ElementName2"); // comma-separated elements
app.toggleVisibility(["ElementName", "ElementName2"]); // list of elements
Toggle Enabled

This action toggles the input state for the elements that you drag and drop from the Layout category. If an element is enabled, it will become disabled. Likewise, if an element is disabled, it will become enabled.

JavaScript Action

app.toggleEnabled("ElementName"); // single element
app.toggleEnabled("ElementName", "ElementName2"); // comma-separated elements
app.toggleEnabled(["ElementName", "ElementName2"]); // list of elements
Set Element Label
Use this action to set a label value for an element. To configure this action, drag and drop the element from the Layout category and then specify the value. You can add a static value, a brace notation (if you need the label to access values from other elements and parameters) or a combination of both. You can format the label using a subset for HTML.
  • As shown by the InputField Element in this image, you can set the set the label value as a static value (My new label).
    This is an image of the Set Element Label configuration.

  • This image shows using static values and brace notation for stored values (Welcome {firstName}).
    This is an image of the Set Element Label configuration.

  • This image shows a combination of a static value, HTML tags and value replacement through brace notation (Welcome <span style=’color: red’>{firstName}</span> ).This is an image of the Set Element Label configuration with the New Label field reading Welcome>span style color red> first name>/span>The following image shows how this combination renders the label at runtime.
    This is runtime image of the label.

JavaScript Action

app.setElementLabel(“ElementId”, “new Label (supporting {} and HTML)”); 

Note:

Using setElementLabel on a Checkbox Element also changes the text that’s next to the checkbox.
Set Element Properties
This action is currently only used to set the properties for the Chart Element. The way chart data is read is app.chartElement.properties.data. This is set as:
app.setElementProperties("chartElement", { "data": d });
app.element.properties is an object that stores properties that are settable with the app.setElementProperties() function. It supports only the data property. For example:
var chartData = app.elements.chartElement.properties.data
app.setElementProperties(elementId, properties) sets a collection of properties on the given element. The properties parameter is a key-value map of the properties to update and their updated value. It supports only the data property. For example:
app.setElementProperties("chartElement", { data: chartData })
Call External Web API

Use this action to call an external API endpoint. To configure this action, specify the API method (GET, DELETE, PATCH, POST, or PUT) and the URL endpoint.

Data from the external web API will be sent to the event that you specify in the Event Name field. To process the returned values, you’ll need to create a Named Callback Event whose name matches the value that you enter in this field. All external web API calls are asynchronous in that they don’t block and wait. Instead, they execute any subsequent actions immediately. When the data is returned from the API call, the specified Named Callback Event will then fire and execute.

If you provide a value in the Data Key field, use brace notation to make the API return data addressable. For example, if your Data Key is called myCurlyData, you can add {myCurlyData.x} to the Elements in the JavaScript that support the curly notation format.

To test various scenarios without actually having to hit the specified endpoint, you can also specify test response and the status code. In Test Mode, when the action is executed, this test response and status code are sent to the named callback event.
This is an image of the Call External Web API configuration.

JavaScript Action

There are six variants of the chatbox.callExternalWebAPI Action:
chatbox.callExternalWebAPI(dataKey, eventName, method, url);
chatbox.callExternalWebAPI(dataKey, eventName, method, url, value);
chatbox.callExternalWebAPI(dataKey, eventName, method, url, value, contentType);


// value and contentType are optional (needed where method equals POST or PUT)
// contentType defaults to application/json if not specified.


chatbox.callExternalWebAPI(dataKey, eventName, method, url, testModeStatusCode, testModeResponse);
chatbox.callExternalWebAPI(dataKey, eventName, method, url, value, testModeStatusCode, testModeResponse);
chatbox.callExternalWebAPI(dataKey, eventName, method, url, value, contentType, testModeStatusCode, testModeResponse);
Activate and Show Pane

This action switches the pane that’s currently active. Using this action, you can switch context and also add wizard-like behavior to your app. To configure this action, drag and drop a pane from the Layout category.

JavaScript Action

app.activatePane("PaneName"); 
Reset Elements

Use this action to reset elements (along with their visibility, label, and value attributes) to their original state. For example, you can configure this action for a form reset button by dragging and dropping the elements that the button resets.

JavaScript Action

app.resetElements("ElementName"); // single element
app.resetElements("PaneName"); // all elements on the specifiedPane
app.resetElements(["ElementName", "ElementName2"]); // list of elements
Play Sound

This action enables your instant app to play a specified sound at a specified volume.
This is an image the Play Sound Action configuration
You can configure this action by selecting one of the built-in sounds or, by choosing the Specify URL option, you can use an external sound file that’s accessed via https. For the latter, you need to enter the URL where the file is hosted (https://example.com/sound.mp3, for example).

There are a few things to keep in mind if you opt for an external sound file:
  • The instant app can only access the file through https.

  • The instant app can’t play a sound if you don’t specify a sound file, or if the file is unavailable or can’t be reached.

  • The file types vary by browser. Typically, browsers support mp3, mpeg, opus, ogg, oga, wav, aac, caf, m4a, mp4, weba, webm, dolby, and flac.

  • For the broadest browser coverage and compatibility, use an mp3–formatted file.

You can test any sound (built-in and external file) by clicking Preview .
This is an image of the external file configuration for the Play Sound Action Preview

Built-in Sounds

  • AscendingTone

  • BellTwinkle

  • DoubleBlip

  • HappyChime

  • OptionChange

  • PercussionBlipsNotic

  • PercussionBlipsPop

  • SlipperyStuttering

  • SuccessAle

  • SuccessChime

JavaScript Action

// supports all the tones from the drop down menu
app.playSound("AscendingTone", 100); // play at full volume

// play a sound from an external website at half volume
app.playSound("https://example.com/sounds/yahoo.mp3", 50);
Show Alert Dialog

This action enables your instant app to display a modal dialog message to its customers.
This is a runtime image of an alert dialog.
Your message definition can include both a limited set of HTML tags and brace notation. For example, Thank you!<br/><b>your order<b> is confirmed, {firstName}.
This is an image of the Show Alert Action configuration.

JavaScript Action

app.showAlertDialog("Thank you!"); 
app.showAlertDialog("Thank you {firstName}"); // use {} value replacement
app.showAlertDialog("<b>Thank you!</b>"); //use of limited HTML
Focus Element

Use this action to move the keyboard focus to a specified element.

JavaScript Action

app.focusElement(“ElementName”); // unlock the app and allow input changes
Open Website
This action enables your app to launch a confirmation dialog, one that opens a URL in a new window after the customer clicks the confirmation button. To configure this message, enter a message and a website URL using one of the following schemes:
Scheme Example
http http://example.com
https https://example.com
sms sms:+12065551212
mailto mailto:support@acme.co
tel tel:+12065551212
ftp ftp://myftp.com

Some URLs, like sms and tel, are not supported by desktop browsers while others (ftp) are not supported by mobile browsers.

JavaScript Action

chatbox.openWebsite("http://example.com", "Let us take you to example.com");
Open Handset SMS

Use this action to display a message dialog, one that opens a phone number when the mobile device user taps a confirmation button with a pre-populated message. You can use brace notation in both the Message and Dialog Message fields to access element values (Thank you, {firstName}.<br><br>Return to SMS).

Some URLs, like sms and tel, are not supported by desktop browsers while others (ftp) are not supported by mobile browsers. Some older mobile phones may not fully support the pre-instantiation of the message

JavaScript Action

chatbox.openHandsetSMS(“MENU”, “12065551212”, “Return to SMS?”);
Set App Status

Use this action to post the app status to the customer record’s audit trail. Each instant app uses a string to indicate its current state. For instance, suppose you have an instant app that is a form. For this, you can add two Set App Status actions, one with a Form Sent string in the Status field and the other with a Form Completed string in its Status field. Users can’t see these status strings, but they get posted to the audit trail and can be searched for analytics. Your string definitions can include brace notation ({ElementOrParameterName}

JavaScript Action

app.setAppStatus("Form Submitted");
Post Audit Trail

Use this action to post a timestamped line of text to the customer record. Your string that specifies the audit trail message can access element or parameter values using the brace notation ({ElementOrParameterName}). For example, First Name Updated {firstName}.

JavaScript Action

app.postAuditTrail("Something happened");
app.postAuditTrail("First Name Updated: {firstName}");
Lock App

Use this action to lock the instant app and prevent users from making any further changes. When this action is fired, the instant app displays an indicator that the instant app has been locked. At this point, your users can no longer click buttons or change any input field. After this action is called, the App Locked Event will fire if any actions are configured for that event.

JavaScript Action

app.lock(); // lock the app from further changes
Unlock App

Use this action to unlock the instant app and allow users to resume with the instant app. In other words, your users can continue to click buttons and change and input values. After this action is called, the App Unlocked Event will fire if any actions are configured for that event.

JavaScript Actions

app.unlock(); // unlock the app and allow input changes
Launch Another Instant App

Use this action to immediately launch another instant app. To configure this action, specify the ID of target instant app. Use the value in the App ID field in the App Settings page.

JavaScript Action

// launch an instant app with no parameters specified
chatbox.launchInstantApp("schemaId",  null);

// launch with specified parameters comma-separated
chatbox.launchInstantApp(
  "schemaId", 
  { name: "paramName1", value: "paramValue1" }, 
  { name: "paramName2", value: "paramValue2" }
);


// launch with specified parameters in an array
var array = [];
array.push({ name: "paramName1", value: "paramValue1" });
array.push({ name: "paramName2", value: "paramValue2" })

chatbox.launchInstantApp("schemaId",  array);

Note that you can’t launch another instant app with parameters.

Exit to Skill

Use this action to enable the instant app to return values to the skill. The instant app remains visually active for the customer even after it returns its values to the skill unless you set actions that enable it to behave otherwise.

Note that returning values to the skill does not alter the visual state or usability of the skill in any way.

While you can define these values as static values, you’re more likely to specify them using curly bracket notation like Hello {nameInput} or {location.longitude} so that they can return values from other elements. For example, the payload returned to the skill would look like this because of the value substitution:
{
"name": "Phil Gordon",
"city": "Seattle",
"longitude": "-32.33221156",
"msg": "Hello Phil Gordon"
}

JavaScript Action

app.exitToBot(); // no parameters
app.exitToBot({ name: "parameter1", value: "value1"}); // exit and send data

Pass Data Between the Instant App and Skill

Parameters pass data from the skill to an instant app and back.

Click +Add Parameter and enter the parameter name in the Parameter ID field in the editor. You can add an optional parameter description which is not seen by the instant app user.
Description of instant_app_parameters.png follows
Description of the illustration instant_app_parameters.png

You reference the parameter ID in the App Sent event through the app.parameters.<parameterName> function to initialize the instant app with the parameter values identified by the System.Interactive’s sourceVariableList property. You can reference the parameter itself, or the values you assign to it (for example, the Element ID name for a UI input widget) using curly brace notation ({parameterName}). See How Do I Reference Parameters in My Instant App to find out how you can set a parameter value on a static UI element and test it

How Do I Reference Parameters in My Instant App?

Here is an example of how to use a parameter to set a label and how to see it work in Test Mode.
  1. Create the parameter. In this case, it’s called CustomerName.

  2. Add a Label element. In the Text field, enter the parameter name and enclose it in curly braces ({CustomerName}).

  3. On the right side of the Instant App Builder (where the phone is), select Test and then click Start as Recipient.

  4. As the admin, you’ll see the Parameter popup, where you can add a name like Jane Doe. Click OK.You’ll see Jane Doe show up on your instant app as your Label element text.

Curly Brace Notation for Element and Parameter Values

When specifying a value for an action, you can both access and use parameters and other element values using brace notation:
  • {ElementName}

  • {parameterName}

When elements have complex object values, you can access their individual key values using the {ElementName.key} notation.

Barcode Element

  • {barCodeName.barcode} —The numeric barcode

  • {barCodeName.barcode.type}—The type of the barcode (AZTEC, CODABAR, CODE_39, CODE_93, or CODE_128)

  • {barCodeName.url}—The URL of the barcode image

  • {barCodeName.html}—The barcode and image as a HTML fragment

Upload Element

  • {uploadElementName.url}—The URL of the uploaded data

  • {uploadElementName.html}—The uploaded data as a HTML fragment

  • {uploadElementName.filename}—The uploaded data’s filename

Location Element

  • {locationElementName.latitude}

  • {locationElementName.longitude}

  • {locationElementName.url.google}—The URL for a Google Maps location

  • {locationElementName.url.bing}—The URL for a Bing location

  • {locationElementName.url.openStreetMap}—The URL for an Open Street Map location

  • {locationElementName.url.hereMap}—The URL for a Here Map location

Date Element

  • {dateElementName.day}

  • {dateElementName.month} — for example, 11 = December

  • {dateElementName.year}

  • {dateElementName.hour}

  • {dateElementName.minute}

  • {dateElementName.epoch} —The number of milliseconds that have elapsed since, for example, 1/1/2018

Note that the epoch value is the easiest way to convert back to the JavaScript date:
var d = new Date(app.Elements.date.value.epoch)

Localize an Instant App

You can localize the instant app’s text strings to the location of the chat client that’s running the skill.

How Do I Localize an Instant App?

Once an instant app is complete, you can localize it by doing the following:
  1. Expand Localizations, then click + Add Location.

  2. Enter the key in the Localization Key file. This key value must match the location parameter passed by chat client. For example, for French, you would use fr-FR. You need to create a separate localization for each language that your skill supports. For example, if your skill passes in Eng-US, Eng-UK, Span-MX, Span-SP, then you need localizations for each of these languages along with an additional localization for the skill's base language if it’s not included in these key parameters. You can’t test the instant app without these localizations.

  3. In the Strings that Need to be Localized and Imported section of the editor, expand Unlocalized Strings to get a view of the current localization coverage. There are two lines for each string. The first names the string ID (which is derived from the Element ID) along with its current text string. It’s commented out using double hashtags (##). The second line names the string ID and a localized string, if one exists. Unlocalized strings (the ones that look like selectMenu_1.tooltip=) render in the original language when the app runs in that language. Otherwise, these labels are blank. You can edit these entries by exporting these strings into a text file. You can localize the strings, but not numbers or dates.

  4. Choose one of the export options and then save the generated .properties.txt file to your local system:
    • Only Unlocalized Strings—For merging new strings into existing localized content.

    • Only Localized Strings—For updating strings or deleting the ones that no longer exist.

    • All Strings—All of the strings, both localized and unlocalized.

    The .properties.txt file does not include strings in JavaScript Snippet actions. It only contains the strings from Instant App Settings and the Layout.
  5. Open the .properties.txt file in the text editor of your choice. Add localizations to string entries. In the following example, label_2.text is not yet localized:
    ## label_2.text=Thanks!\n\nYou have Successfully Registered with us !!!
    label_2.text=
    If you want this label to render in French, then add a new string. Otherwise, the label text won’t render (it will appear blank).
    ## label_2.text=Thanks!\n\nYou have Successfully Registered with us !!!
    label_2.text=Merci.\n\n\Vous avez maintenant terminé le processus d'enregistrement.
    Use comments to track your changes. For example:
    ## label_2.text=Thanks!\n\nYou have Successfully Registered with us !!!
    ##previously > label_2.text=Merci.\n\n\Vous avez maintenant terminé le processus d'enregistrement.
    label_2.text=Bravo!\n\n\Nous êtes arrivés à la fin de la liste.
  6. Save the file as plain text with UTF-encoding.

  7. Import the file back into your instant using one of the following options:
    • Merge new file with Localized Strings—Adds additional stings created from the .properties.txt file generated by the Only Unlocalized Strings.

    • Overwrite all Localized Strings with new file—Use this to delete strings that belong to elements that no longer exist in your app. Typically, you use this in combination with the All Strings option.

  8. Check for warnings. You may need to check for blank strings and errors stemming from deleted elements.

  9. Use the Start as Recipient mode to test the app in all locales.

JavaScript Snippet Localization

You can localize strings in a JavaScript Snippet by creating identifiers in a property file and then referencing them in the snippet using {@.key}. The following snippet, which returns different success or failure strings, references two: {@.custom.success} and {@.custom.failure}.
<span style="font-weight: 400;"><i>//methodCall-> returns status</i>

if (status == "Success") {
   app.setElementValue("displayElement","{@.custom.success}");
} else {
   app.setElementValue("displayElement", "{@.custom.failure}");
}</span>
In the properties file, these identifiers have the following values. When the method call is successful, the instant app displays Exitoso.
custom.success=Exitoso
custom.failure=Fracaso

Use Modes to View Instant App Behavior

While you’re developing your instant app, you can see your work in progress and find out how your instant app behaves at runtime using the following viewing modes that are located at the left of the Instant App Builder:
  • Preview Mode

  • Test Mode

  • JSON

Preview Mode

The Preview mode provides you with the following visual guidelines and functions:
  • The elements that you configure as initially invisible are shown with the hatch marks.

  • The current element that you’ve selected or are editing is outlined in green.

  • Panes are separated by name.

  • Clicking an element in the Preview highlights that element in the Layout section and opens the element’s editor.

    Note:

    Changing values in Preview mode has no effect on the instant app and will not trigger events to fire.

This is an image of the tester in Preview mode.

Test Mode

In Test Mode (which you activate by clicking Test), you’ll see a full preview as well as the Console, which is a running commentary on events and actions as they occur.
This is an image of the Test Mode and the Console.

There are two choices when Test Mode starts: Start as Recipient and Start as Sender. Because an app can behave differently depending on sender or recipient role, you need to pick one of these options before testing the app so that you can assess a particular user experience. For example, you can configure an element’s usability setting that limits the ability to edit a field to only the customer (the recipient).
This is an image of the testing mode options: Start as Recipient and Start as Sender.

Print to Console in JavaScript Snippets

The Test Mode execution comes to a halt whenever you update the instant app (for example, when you edit JavaScript, change an element property or style, etc.), so you’ll need to restart.
print(“Hello World”);

Limitations of Test Mode

There are few things to keep in mind while using Test Mode:
  • The Call External Web API action can’t call the target resource. Instead, it uses test data that you’ve provided in the Test Response field. You also need to provide a response code.

  • You can’t use the Lock App and Unlock App actions.

  • If the instant app requires any parameter data, you’ll be prompted it when Test Mode starts.
    This is an image of the parameters popup dialog. The fields are empty.

JSON

The JSON tab displays the complete specification for this instant app as expressed in JSON. While you can export this JSON, modify it using the code editor of your choice, and then import it to the Instant App Builder, you can avoid validation errors and other problems (like creating or improper or inconsistent schemas) if you create the app entirely with the Instant App Builder. See Export and Import an Instant App.

Instant App Lifecycle

You can manage your library of instant apps by activating and deactivating them, deleting them, making clones that you can edit, or by editing the app directly.

You access these management functions from hamburger menu on the bottom right of an instant app tile.
This is an image of the Edit menu opened from an instant app tile.

Edit

You can edit any instant app in your library in one of two ways: simple Edit, or Edit a Copy.

Simple editing takes you into the existing instant app to make changes. Once you’ve completed your changes, clicking Save overwrites the existing version. If you choose Edit a Copy, your instant app will be cloned. Any changes that you make will be saved to a new instant app, with the default name Copy of (original instant app name). Rename, make edits, and save your new instant app.

Publishing

An inactive instant app's name and description are grayed out and italicized. If you have an inactive instant app in your library, you can reactivate it by choosing Activate from the tile's menu.

Deactivate

Similar to activating an instant app from your library, you can use the hamburger menu on the instant app tile to deactivate it.

Delete, Archive, and Restore

You can delete and archive an instant app by choosing ... on the instant app tile.
This image shows the delete option accessed from the tile menu.

Once you’ve archived the instant app, you can find it by opening the instant app and expanding the Archived dropdown.

To delete an instant app, expand the Archived Instant Apps drop down, click ... on the instant app tile, then select Delete.

Note:

Take care when choosing Delete. This option permanently deletes the instant app.

To unarchive or delete an archived instant app, expand the Archived Instant Apps drop down, click ...on the instant app tile, then select one of the options from the menu. Unarchived instant apps can be found on the instant app landing page.

Export and Import an Instant App

Export

You can export any instant app into a JSON file. To do so, open the Instant App Builder and click ... on the app’s tile and select Export. From the file manager window, select where you want to save the file. This JSON file can be edited however you'd like.

Import

To import an Instant App JSON file, open the Instant Apps landing page and select Add Instant App. Select Import, then drag the file to the drop box area. Alternatively, click Upload a Schema File and navigate to the file.
This image shows the Import Instant App screen with a bordered section in which you can drag and drop a schema file, or click on a link to upload a schema file.
Once the instant app is uploaded, it opens in the builder where you can make changes to the file.