WhatsApp Business Messages Templates — Flow Messaging Template

Disclaimer

As of this release, the implementation has been tested with the Flow JSON model version 7; the following functionalities are not available or may be limited:

Sending Template Messages
Setting up Endpoint-driven Flows
Media Upload (including images and documents)
Chips Selector as well multi-option answers such as CheckboxGroup
Bot correlating the consumer’s response to the shared Flow message

Overview

We are excited to introduce the integration of WhatsApp Flow Messaging.

With this, it is possible to trigger WhatsApp Flows within bot conversations and act on Flow results.

WhatsApp Flow Message on Consumer Side

WhatsApp Flow Message on LivePerson's Side

Get Started

Throughout this document, the abbreviation "WAM" refers specifically to "WhatsApp Manager".

This document offers guidance on using WhatsApp Flows within LivePerson and is not connected to the Flow build process in WAM.

Prerequisites (technical)

A Flow is created in WAM. See how here.

Flow Structured Content

The following JSON structure represents how LivePerson links the message to a WhatsApp Flow in WAM.
(ready-to-use JSON can be found in Complete Examples)

// Structured Content JSON (LivePerson specific)

{
  "type": "vertical",
  "tag": "flow",
  "elements": [
    { // optional
      "type": "text",
      "tag": "header",
      "text": "Flow message header"
    },
    { // required
      "type": "text",
      "tag": "body",
      "text": "Flow message body"
    },
    { // optional
      "type": "text",
      "tag": "footer",
      "text": "Flow message footer"
    },
    { // required
      "type": "button",
      "title": "Signup now!", // the text visible in the consumer's button
    },
    {
      "type": "keyValuePairList",
      "elements": [
        { // optional
          // defaults to "published"
          "key": "mode",
          "value": "<published|draft>" // the "status" of the Flow in WAM
        },
        { // either flowName or flowId is required, can't be used together
          // interchangeable w/ flowName
          "key": "flowId",
          "value": "<flow-id-from-wam>"
        },
        { // either flowName or flowId is required, can't be used together
          // interchangeable w/ flowId
          "key": "flowName",
          "value": "<flow-name-from-wam>"
        },
        { // optional, but required if you have flowActionPayloadData
          "key": "flowActionPayloadScreen",
          "value": "<first-screen-id>"
        },
        { // optional
          // also known as dynamic properties
          "key": "flowActionPayloadData",
          "value": "{\"<flow-json-var-name1>\":\"<value1>\",\"<flow-json-var-name2>\":\"<value2>\",\"<flow-json-var-nameX>\":\"<valueX>\"}"
        }
      ]
    }
  ]
}

The purpose of the field “flowActionPayloadData” is to send specific data from LivePerson's bot to the WhatsApp Flow (see full example below).

To understand how the dynamic properties are used, please refer to the FAQ section.

Integrating a Flow into Conversation Builder

Create a Bot

A Bot for handling agent ↔ consumer conversation can be set up by following this documentation.

Add a Dialog

Inside the Dialogs page of the Bot, the Universal Tile can be used to send out a Flow message to consumers:

WhatsApp Bot Universal Tile Block

Click on the Universal Tile to add a new interaction in the dialog. Then click on + Enter JSON and preview:

Whatsapp Bot Universal Tile Enter Json

Next, enter the JSON structure from Flow Structured Content, remove the comments and adapt it accordingly to your newly set-up Flow. You can take the required data for all fields in the WAM → Flows page.

You need to change the flowId (or flowName), flowActionPayloadScreen (which might be optional) and mode properties from the keyValuePairList object.

To understand how to select the value of flowActionPayloadScreen, please refer to the FAQ section.

flowId → the ID from the “Flow ID” column of the desired Flow
flowName → the name of the flow from the “Flow” column
flowActionPayloadScreen (optional) → Click on the Flow → In “Editor” mode (you may need to click on the “Edit” button in the top right corner, if the Flow is in a published state) → under the screens array → copy the id from the first element
mode → the “Status” column → according to the current status, the value should be published or draft

Finally, press the Save button in the bottom right corner of the page.

Example Preview

WhatsApp Bot Flows Example Preview

Understanding the Response

Click on the Custom Code button in the Universal Tile interaction:

Then navigate to the Process User Response tab:

Here, to process the consumer's response, paste the following code:

var flowContent = botContext.getLPEngagementAttribute("richContent");

// in case the submitted by the consumer message is not a RichContent response
if (!flowContent) return;

var flowContentJSON = JSON.parse(flowContent);

// in case the submitted by the consumer message is not a response to a WhatsApp Flow
if (flowContentJSON.tag != "whatsapp-flow") return;

var flowContentElements = flowContentJSON.elements;

function transformFlowDataToObject(flowData) {
    return flowData.reduce(function (acc, flowItem) {
        if (flowItem.type === 'horizontal') {
            var flowFieldKeyElement = flowItem.elements.filter(function (el) { return el.tag === 'key'; })[0];
            var flowFieldValueElement = flowItem.elements.filter(function (el) { return el.tag === 'value'; })[0];

            if (flowFieldKeyElement && flowFieldValueElement) {
                acc[flowFieldKeyElement.text] = flowFieldValueElement.text;
            }
        }
        return acc;
    }, {});
}

var result = transformFlowDataToObject(flowContentElements);

// for validation that the bot has read the consumer's data correctly
// uncomment the line below to send the parsed JSON object to the conversation transcript in Agent Workspace
// botContext.sendMessage(JSON.stringify(result));

// the value in the variable "result" should be similar to:
// {"purchase_experience_rating":"5","delivery_rating":"4","customer_service_rating":"3","would_recommend":"1","how_to_do_better":"So, everybody loves coffee"}

If the Flow does not capture or submit any data, a default message is sent to the Bot Agent, reading:

The user has completed the Flow, but no data was captured or submitted.

Complete Examples

Make sure to adapt the examples to your specific Flow as explained here.

Simple Structured Content JSON

{
  "type": "vertical",
  "tag": "flow",
  "elements": [
    { 
      "type": "text",
      "tag": "header",
      "text": "Flow message header"
    },
    {
      "type": "text",
      "tag": "body",
      "text": "Flow message body"
    },
    { 
      "type": "text",
      "tag": "footer",
      "text": "Flow message footer"
    },
    {
      "type": "button",
      "title": "Signup now!"
    },
    {
      "type": "keyValuePairList",
      "elements": [
        {
          "key": "flowName",
          "value": "simple_flow"
        }
      ]
    }
  ]
}

Structured Content JSON with Dynamic Properties

{
  "type": "vertical",
  "tag": "flow",
  "elements": [
    { 
      "type": "text",
      "tag": "header",
      "text": "Flow message header"
    },
    {
      "type": "text",
      "tag": "body",
      "text": "Flow message body"
    },
    { 
      "type": "text",
      "tag": "footer",
      "text": "Flow message footer"
    },
    {
      "type": "button",
      "title": "Signup now!"
    },
    {
      "type": "keyValuePairList",
      "elements": [
        {
          "key": "flowId",
          "value": "1232124351149531"
        },
        {
          "key": "flowActionPayloadScreen",
          "value": "WELCOME_SCREEN"
        },
        {
          "key": "flowActionPayloadData",
          "value": "{\"hello_world_heading\":\"Hello Dynamic World!\",\"hello_world_body\":\"Let's start building dynamic things!\"}"
        }
      ]
    }
  ]
}

FAQ

Q: What is the purpose of selecting a screen in the flowActionPayloadScreen property?
- A: It defines which "entry screen" will be initially displayed on the consumer’s device when the flow starts.
Q: What is an "entry screen"?
- A: An "entry screen" is a screen defined in WAM that exists within the Flow JSON and is not referenced as the "next" screen by any other screen in the flow. A Flow JSON can contain multiple entry screens. For guidance, see the Routing Rules section in Meta's documentation.
Q: What do I need to do to use the flowActionPayloadData (also known as "dynamic properties")?
- A: The dynamic properties are passed to the specified entry screen. On Meta's side, you must configure the screen to expect and handle these properties. For guidance, see the Optional properties and Declaring screen properties sections in Meta’s documentation.
Q: What if a Flow is used that returns results from a password field?
- A: It is received as plain-text on LivePerson's side.
Q: Do we support complex types of fields?
- A: We support only simple-structured fields for the moment.
  - Including text fields and single-option elements like radio buttons, dropdowns, etc.