Guiding customers with journeys

Creating a journey

A journey is defined using the user_defined response type, which is available only in the JSON editor. (For more information, see Defining responses using the JSON editor.) To create a journey, follow these steps:

1. In the action editor, create or edit the step from which you want to start the journey.

2. Click the Switch to JSON editor icon to open the JSON editor.

3. In the generic array, create a user_defined response. (For more information, see Defining responses using the JSON editor.)

   A journey is defined using the following structure:

   "user_defined": {
     "user_defined_type": "IBM_BETA_JOURNEYS_TOUR",
     "skip_card": true|false,
     "card_title": "{title}",
     "card_description": "{description}",
     "steps": [
       ...
     ]
   }
   

   where:

   user_defined_type

   The specific type of user-defined response you are defining. To define a journey, always set this property to IBM_BETA_JOURNEYS_TOUR.

   skip_card

   An optional property that specifies whether the web chat should start the journey immediately without waiting for the customer to click the introductory card in the web chat window. (The default value is false.)

   You can use this option to start a journey directly from your website, even if the web chat is not open. For more information, see Starting a journey without opening the web chat.

   card_title

   The title to display on the introductory card that appears in the web chat when a journey is available (for example, Website tour or Disputing a charge).

   card_description

   The description to display on the introductory card. Describe the journey so your customers can decide whether they want to open it.

   steps

   An array of responses defining the steps in the journey.

Example

The following example defines a journey that shows users how to dispute a charge, using a combination of text, image, and video responses.

{
  "generic": [
    {
      "response_type": "user_defined",
      "user_defined": {
        "card_title": "Let’s dispute a charge!",
        "card_description": "Follow along with this guided journey to learn how to find and dispute charges.",
        "user_defined_type": "IBM_BETA_JOURNEYS_TOUR",
        "steps": [
          {
            "response_type": "text",
            "text": "Charges are listed on the Transactions page. **Click your profile photo** in the top right corner of your screen, and then **click Transactions** from the menu."
          },
          {
            "response_type": "text",
            "text": "Here you can view your charges.\n **Scroll through the Transactions page and review your charges.** Each charge contains a merchant name, transaction date, and amount charged."
          },
          {
            "response_type": "image",
            "source": "https://example.com/image.png",
            "alt_text": "Image showing location of Dispute option",
            "description": "The option to Dispute is marked in red on the right hand side of each row in the Transactions table. Just click here to file a dispute."
          },
          {
            "response_type": "video",
            "source": "https://vimeo.com/769580398",
            "description": "Watch this short video to learn what to expect now that you’ve filed a dispute."
          }
        ]
      }
    }
  ]
}

Starting a journey without opening the web chat

Although journeys are part of the web chat integration, you can make it possible for your customers to start a journey directly from your website without opening the web chat window at all. For example, you might want to include a Show me button on your website that customers can click to launch an interactive tour of the page.

To start a journey without opening the web chat:

1. In the action that sends the journey response, edit the JSON that defines the journey. Include "skip_card": true to bypass the introductory card.

2. On your website, use the send() instance method to send a message to the assistant that triggers the action that starts the journey (such as Give me a tour). Send the message in response to whatever event you want to use to trigger the journey (such as a button click or page load).

Your customers can now start the interactive journey directly from your website without having to open the web chat first. (If the web chat window is opened later, the introductory card for the journey appears in the chat history.)

Limitations

This beta feature currently has the following limitations:

• The preview pane does not support journeys. If you want to preview a journey, use the shareable preview link. For more information about the preview link, see Copying a link to share.

• Journeys use the view:change event or changeView method, and do not work with the window:open or window:close events or the openWindow, closeWindow and toggleOpen instance methods.

• When the customer starts a journey, the web chat window closes. If you are using the view:change event to trigger the display of a post-chat form, your code should check the value of the new event.reason or event.newViewState.tour parameter to decide if showing the form is appropriate.