Application Development

Using Oracle Instant Apps in Oracle Digital Assistant

Help your app users input structured data.

By Frank Nimphius

January/February 2019

Building chatbots that assist users via a conversational interface is not about technology alone—it requires conversational design skills as well. Good conversational design aims to deliver the best-possible guidance and help to a user completing a bot task. Good guidance, however, may require navigating users out of the conversational channel and into a web view if, for example, data input would be cumbersome and painful otherwise.

Using the hands-on instructions in this article, you are going to complete the implementation of a flower-ordering application that uses a web view to define the recipient’s name and address as well as delivers the sender’s name and a short message with the flowers. To do all this, you will use Oracle Instant Apps, a feature of Oracle Digital Assistant.

About Oracle Digital Assistant

Oracle Digital Assistant is the next generation of the Oracle’s chatbot solution. It manages and coordinates multiple smaller-scoped skill bots to a composite chatbot solution that assists users in completing multitask conversations. You can imagine Oracle Digital Assistant as a concierge bot that intelligently routes user requests to the skill bot that best matches the user query. If you used Oracle Intelligent Bots in the past and you read previous Oracle Magazine articles about the technology, then you will recognize the bots you created with the tool (or read about) as skill bots in Oracle Digital Assistant.

About Instant Apps

Instant apps are reusable microscoped web applications you build declaratively for use in the context of a skill bot conversation. At runtime, instant apps are executed in the mobile device’s web view or a browser window outside of the conversational channel.

Oracle Instant Apps enables bot designers to create instant apps to provide users with an easy way for entering structured form data in a bot conversation. However, Oracle Instant Apps also provides cross-messenger support for a set of user interface components such as charts, a signature, YouTube, and many others that don’t natively exist in messengers. Figure 1 and Figure 2 show common and special user interface elements currently available in Oracle Instant Apps.

chatbots figure 1

Figure 1: Oracle Instant Apps common user interface components

chatbots figure 2

Figure 2: Oracle Instant Apps special user interface components

You integrate instant apps into a skill bot conversation by adding the System.Interactive system component to the dialog flow. You can pass input parameters to an instant app at launch time and receive return data when the instant app exits.

Getting Ready

The use case for the hands-on example in this article is a simplified version of a flowerordering bot. A starter bot is provided so that you need to focus only on implementing the Oracle Instant Apps integration by following the instructions in this article.

The following are prerequisites for following along with the hands-on steps in this article:

Follow these initial hands-on steps to start the service and import, train, and test the bot.

  1. Start Oracle Digital Assistant in a browser by typing https:///botsui/ into the URL field.
  2. Click the hamburger icon () located in the top left corner.
  3. Choose Development and then Bots.
  4. Close the menu by clicking the hamburger icon ().
  5. Click the Import Bot button in the upper right corner.
  6. Navigate to the downloaded and extracted resources for this article, and navigate to the starter folder.
  7. Select the starter bot file, and click Open.
  8. Click the OracleMagazineTwenty4hoursFlowers tile in the bot dashboard to open the bot.
    Note: If you don’t see the imported bot because other bots fill your screen, type OracleMagazine into the Filter field above the + New Bot tile.
  9. Train the bot by clicking the Train link () in the top right.
  10. In the opened dialog box, accept the default settings and click Submit.
  11. Run the embedded bot tester by clicking the Test icon () in the top right.
  12. Type Hi into the Message field, and click Send.
  13. In the displayed menu, select a flower type.
  14. Follow the bot conversation, and provide input values for all bot questions.
    Note: The bot conversation does not validate input other than the input type. So when you are asked for a credit card number, you can enter 1234567. The same approach works for the expiration date.
  15. Click the Yes or No button when asked, “Do you want to submit this order?”
  16. Click Reset to run the flower order bot again. This time, type I like to order 12 red roses for overnight delivery to be charged to my AMEX.
  17. Complete the bot conversation as you did earlier.

What you just did: Following the instructions above, you imported, trained, and tested the provided starter bot.

You experienced the conversation from the perspective of a new user (starting the conversation with Hi) and a returning user (starting the conversation with a more detailed input phrase). Both conversations ended with questions about the name and address of the flowers’ recipient, your credit card number and its expiration date, and the name to put on the card along with a greeting message.

Adding a Dialog Flow State for Instant Apps

The conversation you experienced is a bit long for a simple task such as ordering flowers. Ideally, you’d want an input form to be provided where the user could edit it in a single block of input fields. And this is exactly what you are going to do next, using Oracle Instant Apps.

  1. Click the Flows icon () to open the dialog flow editor.
  2. Navigate to the askCreditCardNumber state in line 142.
  3. Delete all content from line 142 to line 188 (inclusive).
  4. Change line 140 to next: "getOrderPaymentAndDeliveryDetails".
  5. Scroll to the top of the dialog flow window.
  6. Click the + Components button ().
  7. In the opened dialog box, select the User Interface category.
  8. In the User Interface component dialog box, select the Interactive option.
  9. Set the value of the Insert After list box to askPaymentType.
  10. Toggle the Remove Comments switch so it is enabled.
  11. Click the Apply button.
  12. Change the name of the added state from interactive to getOrderPaymentAndDeliveryDetails. The state should look as shown in Figure 3.

    chatbots figure 3

    Figure 3: askPaymentType and getOrderPaymentAndDeliveryDetails states

  13. Navigate to line 29.
  14. Add to line 29 a new context variable of type string with the name instantAppReturn, as shown in Figure 4.

    chatbots figure 4

    Figure 4: instantAppReturn context variable declaration

  15. Navigate back to the getOrderPaymentAndDeliveryDetails state (line 142) and edit the properties as shown in the table below (include the surrounding quotes for the values):
    Property Name Value
    sourceVariable-List "orderProductName,orderNumber"
    variable "instantAppReturn"
    id "orderPaymentAndDelivery"
    prompt "Please provide payment and delivery information"
    linkLabel "Please click to launch the edit form"
    cancelLabel "No, thanks. Cancel order."
    cancel "exitBot"
  16. Delete textReceived: action (line 155).
  17. Compare your configuration with Figure 5. Ensure that it looks the same.

    chatbots figure 5

    Figure 5: System.Interactive component state with configuration

  18. Click the Validate link () at top of the dialog flow editor, and correct any formatting errors.

What you just did: In this part of the hands-on steps, you first used Oracle Instant Apps to remove the dialog flow states that handled the part of the conversation that you want to shorten. You created and configured a new dialog flow state: getOrderPaymentAndDeliveryDetails. You also created a new context variable, instant­AppReturn, for Oracle Instant Apps to return values to.

Building the Instant Apps

Now use Oracle Instant Apps to build new functionality.

  1. Start by clicking the Instant Apps button at the top of the page.
    Note: Instant App Builder opens in a separate tab. If the tab doesn’t open, check for and disable any popup blocker that may be active in your browser.
  2. In Instant App Builder, click Add Instant App.
  3. Click Start from Scratch.
  4. Enter orderPaymentAndDelivery in the Name field of the instant app.
  5. Press the Tab key to navigate to the API ID field.
  6. Enter orderPaymentAndDelivery in the APP ID field.
  7. Click Save.
  8. In the dialog box that opens, click Got It!
  9. Select the LAYOUT tab.
  10. In the Pane ID field, enter EditOrder, as shown in Figure 6.

    chatbots figure 6

    Figure 6: Setting the pane name to EditOrder

  11. For each item in the table below, follow these steps:
    1. Within the pane, click Add Element.
    2. In the palette in the middle of the designer, click the button for the element type shown in the second column (such as Image, Single-Line Input, or Button).
    3. In the Element ID field, enter the element ID shown in the third column.
    4. Fill in the properties that are specified for that element in the fourth column of the table.
    Order Element Type Element ID Properties
    1 Single-Line Input inputProductOrder Initially Enabled: Uncheck, Label: Product Order
    2 Single-Line Input inputRecipientName Label: Recipient Name
    3 Single-Line Input inputRecipientAddr Label: Recipient Address
    4 Single-Line Input inputCreditCardNo Label: Credit Card Number
    5 Single-Line Input inputCreditCardValid Label: Expiry Date
    6 Single-Line Input inputSenderName Label: Sender Name
    7 Single-Line Input inputSenderMessage Label: Message to go on card
    8 Button btnSubmit Label: Submit
    Hint 1: As an alternative to using the Add Element button, you can drag and drop UI elements directly into the layout. This is useful when you want to insert an element in a specific place.
    Hint 2: If you need to delete an element, first select it, then click the ellipsis (...) icon that appears, and then select Delete.
  12. Click the PARAMETERS tab.
  13. Within the PARAMETERS tab, click Add Parameter.
  14. In the Parameter ID field, enter orderProductName.
  15. Again, click Add Parameter, and in the Parameter ID field, enter orderNumber.
    Note: Parameters are named to match the context variable names that are passed from the bot to the instant app. (If they don’t match, they won’t work correctly.)
  16. Now you will assign values to the matching UI elements, based on data retrieved from the parameters. To do this, first expand the LAYOUT tab.
  17. Click EVENTS & ACTIONS, and then click the App Sent button (shown in Figure 7).

    chatbots figure 7

    Figure 7: Select EVENTS & ACTIONS, and click the App Sent button.

  18. Click Add Action.
  19. Select Set Element Value.
  20. Drag the inputProductOrder layout component (under LAYOUT->EditOrder) to the Drag and drop elements from the Layout field area in the tile for the action.
  21. In the New Value field, enter {orderNumber} - {orderProductName}. Now add a message page to display a message for the user to close the web view when the Submit button is clicked.
  22. In the LAYOUT section, click Add Pane.
  23. In the Pane ID field, type CloseMessage.
  24. In the CloseMessage pane, click Label / Text to create a label.
  25. In the Element ID field, enter doneMessage.
  26. In the Text field, enter Your payment and delivery options have been saved. You can now close the browser tab and return to the bot.
  27. Select the EVENTS & ACTIONS tab.
  28. Select the btnSubmitPressed tile in the EditOrder Events section.
  29. Click the + Add Action button.
  30. In the opened dialog box, scroll to the bottom and click the Activate and Show Pane button.
  31. Drag the CloseMessage pane from the LAYOUT tab to the Drag and drop a Pane from the Layout field.
  32. Once again, click Add Action.
  33. In the opened dialog box, scroll down to the bottom and click the Exit to Bot tile.
  34. In the Parameter Name field, enter recipientName.
  35. In the Parameter Value field, enter {inputRecipientName}.
  36. Fill in the rest of the parameters for the Submit action by clicking Add Parameter and entering the Parameter Name and Parameter Value for each of the rows in the table below:
    Parameter Name Parameter Value
    recipientAddress {inputRecipientAddr}
    creditCardNumber {inputCreditCardNo}
    creditCardValidDate {inputCreditCardValid}
    senderName {inputSenderName}
    senderMessage {inputSenderMessage}
  37. Click Save to save the new instant app.
  38. Click Test (on the right) to test the Edit Order instant app.

What you just did: In this part of the hands-on steps, you created a web form where the bot user can provide payment and delivery information for a given order. Note that the form you created does not validate the user input, though this could be done using Oracle Instant Apps. When the user exits the instant apps form, the values of the input fields are returned to the bot, where they can be accessed through the instantAppReturn variable.

Apply Final Changes to the Dialog Flow

So far, the order confirmation is printed from context variables. With your new instant app, some of the values are now saved in the instantAppReturn context variable. Next you are going to change some of the context variable references to instead point to the instant app return values.

  1. In the dialog flow editor, navigate to the orderSummaryCntd1: state.
  2. Change ${recipientName.value} to ${instantAppReturn.value.recipientName}.
  3. Change ${recipientAddress.value} to ${ instantAppReturn.value.recipientAddress}.
  4. Navigate to the orderSummaryCntd2: state.
  5. Change ${creditCardNumber.value} to ${instantAppReturn.value.creditCardNumber}.
  6. Navigate to the orderSummaryCntd3: state.
  7. Change ${senderName.value} to ${instantAppReturn.value.senderName}.
  8. Change ${senderMessage.value} to ${instantAppReturn.value.senderMessage}.

Testing your Bot

Now see how your instant app form works with the bot.

  1. Click the Test icon () in the upper right.
  2. Click the Reset button at the top of the tester.
  3. In the message field, type I like to order 12 red roses for overnight delivery to be charged to my AMEX.
  4. Click the Send button.
  5. Click the Please click to launch the edit form link.
  6. Fill in all the form fields in the opened browser tab. (Because there is no validation applied to the form, you don’t need to provide a real credit card number.)
  7. Click the Submit button.
  8. Close the browser tab.
  9. Back in the bot, you should see the printed order confirmation with the information you added in the instant app.
    Note: It may happen that the callback from the instant app failed for the embedded tester. In this case, you won’t see a print statement. If this happens, click the Reset button and try again.


This article introduced Oracle Instant Apps, a feature of Oracle Digital Assistant that bot designers can use to simplify structured data entry or to shorten otherwise lengthy conversations. You can look at Oracle Instant Apps as a tool and an option to use when your bot design would benefit from it.

Next Steps

TRY Oracle Digital Assistant.

LEARN more about Oracle Mobile Cloud Enterprise and Oracle Intelligent Bots.

DOWNLOAD the bot for this article.

Illustration by Wes Rowell