WhatsApp Flows in Journeys

Hasan Tariq Updated by Hasan Tariq

A WhatsApp Flow allows you to have a more structured interaction in your messaging, like a form inside WhatsApp. Think of it as giving customers a range of choices and then drilling down into those choices through various screens to get very accurate and structured information. These choices can be in different formats like text boxes, unique and multiple-choice selections, date pickers, etc (click here for a complete list).

Meta provides an example where businesses guide interested buyers toward a purchase by first showing a high-level overview of available products. Customers can then select their preferences to narrow down to a specific item, ending with a link to complete payment.

Creating a WhatsApp Flow

Create the Flow in the WhatsApp Manager by going to Account Tools > Flows. Click on "Create Flow":

WhatsApp Flows are created with a coding language called Flow JSON.

If you're not comfortable with writing JSON, you can always use Meta's Playground to build Flows visually, and then copy the Flow JSON and paste it into your Flow: https://developers.facebook.com/docs/whatsapp/flows/playground

Example: creating a simple date picker Flow

When you need to get a date from a user, asking them to type it can be problematic. Users might send "12-08-2025," "next Monday," or "Aug 12," which requires your service to interpret many different formats. The WhatsApp Flows DatePicker solves this by presenting a simple, interactive calendar. This improves the user experience and provides you with a perfectly formatted date, every time.

There are two main steps to get the DatePicker working in your Journeys.

1. Create the WhatsApp Flow with JSON on Facebook Business Manager

First, you need to navigate to your WhatsApp Business Manager > Flows and click on "Create Flow".

Meta allows you to start with a sample flow that they have already created. Otherwise, you can just select "Default", which starts an empty Flow, and click Create:

Turn.io currently does not support Flows under the "With Endpoint" heading so please ensure that you are choosing one of the options under "Without Endpoint".

Now, simply copy and paste this code into your Flow and save it:

{
  "screens": [
    {
      "data": {},
      "id": "APPOINTMENT_SCREEN",
      "layout": {
        "children": [
          {
            "children": [
              {
                "label": "Your Date of Birth",
                "name": "Date_of_Birth",
                "required": true,
                "type": "DatePicker",
                "helper-text": "Please select your Date of Birth"
              },
              {
                "label": "Continue",
                "on-click-action": {
                  "name": "complete",
                  "payload": {
                    "date": "${form.Date_of_Birth}"
                  }
                },
                "type": "Footer"
              }
            ],
            "name": "flow_path",
            "type": "Form"
          }
        ],
        "type": "SingleColumnLayout"
      },
      "terminal": true,
      "title": "Date of Birth"
    }
  ],
  "version": "7.2"
}

To understand how this code works, expand the Details section below:

Details
Understand the Key JSON Properties
To use this code effectively, you need to know what the key properties do.

id: "APPOINTMENT_SCREEN": This is a crucial piece that is required on the Turn.io side in order to let what screen from this flow to start for a user since a flow can have multiple screens.

type: "DatePicker": This is the essential component that tells WhatsApp to show a calendar interface.

name: "date": This is the identifier for the data you get back. After the user selects a date and clicks "Complete," your service will receive the data with this name (e.g., {"date": "2025-10-20"}).

label: "Pick the date of your appointment": This is the text prompt that is displayed to the user above the calendar selector.

min-date: "2024-09-06": This property is used for validation. In this example, it prevents the user from selecting any date before September 6, 2024.

type: "Footer" and label: "Complete": These properties create the submission button that the user will tap to confirm their selected date. When tapped, the flow will close and send the data back to your service.

The complete documentation for flows can be found at Meta.

Once the code is saved, you can preview what the Flow would look like for an end-user on the right hand side of the flow code.

Publish

If you are satisfied with the experience, you can publish the flow, which then makes it possible to use it within Turn.

2. Call the Flow within a Journey

After having writing, saved and publishing the flow you are now able to use it within Journeys. There are two options:

2.1 Use the Flow card

Simply add the new Flow card into your Journey and select the Flow you created:

Flows can't be previewed on the simulator. To test it, you need to use WhatsApp.

If you need to access the results of your Flow, simple use the card's reference.. For example, if you're collecting a name and age, and your card is called Flow_1, they'd be accessible in @ref_Flow_1.name and @ref_Flow_1.age. You can then use this data to update the user's profile, make API calls, branch the Journey, or whatever you'd like to do.

If your Flow has multiple screens, you can also specify which page it should start with by referencing that screen's id on the sidebar:

If during a Flow the user types a message back, the Journey will continue to the "not completed flow". If the user fills out the Flow after that, the journey will not go back on the Flow results path:

Flows can also be used to edit existing data. To do that, you can pass any data into a Flow using the Initial data data on the sidebar:

Flows also have the ability to use expressions and variables in this data. Using variables to prefill the Flow can be very powerful:

On your Flow JSON, you also need to be expecting this data. You need to define data in the WhatsApp flow definition, as well as init-value for each input field you're passing initial data for:

{
    "version": "7.2",
    "screens": [
        {
            "id": "START_SCREEN",
            "title": "Hello World",
            "terminal": true,
            "success": true,
            "data": {
              "name": {
                  "type": "string",
                  "__example__": "John"
              },
            },
            "layout": {
                "type": "SingleColumnLayout",
                "children": [
                    {
                        "type": "TextInput",
                        "name": "name",
                        "label": "Name",
                        "init-value": "${data.name}"
                    },
                    …
                ]
            }
        }
    ]
}

2.2 Use the code block

The code function to be used that allows you to send out a WhatsApp flow is:

whatsapp_flow("Continue", "your_flow_id", "APPOINTMENT_SCREEN")

Parameter

Description

Continue

The text to be displayed on the button that the flow generates. The flow only starts when the user clicks this button.

your_flow_id

This can be found by navigating back to the Flow page where you create a flow from. Each flow has its "Flow ID" listed on this and you can copy this.

APPOINTMENT_SCREEN

The name of the screen from the flow that should be shown at this point in time. A single flow can have multiple screens. For our code in Step 1 we only had this single screen.

The documentation for using WhatsApp Flows on Turn.io within different scenarios can be found here. However, a simplistic example incorporating the flow code that we defined above is shown below.

card Flow do
  flow =
    whatsapp_flow("Continue", "your_flow's_id", "APPOINTMENT_SCREEN") do
      header("this is the header")
      text("this is the body")
      footer("this is the footer")
    end

  then(ThankYou when has_text(flow.date))
  then(Other)
end

card ThankYou do
  text("Thank you! Your appointment is scheduled for @flow.date")
end

card Other do
  text("You did not select a date.")
end

The above allows you to send a flow to the user with a text body, a footer, a header and a button as showcased below. You can of course, choose to not send the text body, footer and header.

The subsequent lines of code within the code above allow you to access the date the users picket with the "@flow.date" variable. Any variable defined within the flow code can be accessed in this way once the flow ends. A Journey will not move forward up and until the flow either completes or the user cancels it. Which is why you can see that we check if the user did indeed select a date and branch our Journey on the basis of that.

Was this article helpful?

Cards and Messages types

Journeys Data

Contact