WhatsApp Flows in Journeys

Hasan Tariq Updated by Hasan Tariq

Since Turn.io does not have the ability to create flows within the product itself and since WhatsApp flows require coding of their own format, Turn can not help you create custom codes. However, for a simple use case, as the DatePicker, we have pasted the code below. It defines the structure and content of your DatePicker screen. This is done using a JSON object.

Why Use a DatePicker Instead of Text?

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.

How to Implement the DatePicker

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 through your Facebook Business Manager. Once you are able to see a variant of this screen you are at the correct place.

You will need to click on "Flows" under the "Account Tools" heading. Once you are in the flows tab, click on "Create Flow".

Meta allows you to start with a sample flow that they have already created by selecting an option other than "Default". However, for this use case we will be proceeding with the "Default" option since we already have the code implemented below.

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".

You can copy paste this code in the Flow code editor and save it:

The JSON Code:

{
    "version": "7.2",
    "screens": [
        {
            "id": "APPOINTMENT_SCREEN",
            "layout": {
                "type": "SingleColumnLayout",
                "children": [
                    {
                        "type": "Form",
                        "name": "appointment_date_form",
                        "children": [
                            {
                                "type": "DatePicker",
                                "name": "date",
                                "label": "Pick the date of your appointment",
                                "required": true,
                                "min-date": "2024-09-06"
                            },
                            {
                                "type": "Footer",
                                "label": "Complete",
                                "on-click-action": {
                                    "name": "complete"
                                }
                            }
                        ]
                    }
                ]
            },
            "title": "Appointment Reminder Date",
            "terminal": true
        }
    ]
}

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.

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

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.

2. Call the Flow within a Journey

After having writing, saved and publishing the flow you are now able to use it within Journeys. In order you use flows, you will need to use a code block if you are working within the no-code canvas. Please do note that the code we defined earlier in step 1 represents how the flow will work once it is started for a user whereas this step focuses on how to send this flow to a user and customize it.

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 ofcourse 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.

Please do not that you need to be in an active conversation window in order to be able to send Flows. Flows are not a substitute for templates.

Was this article helpful?

Conversation Design Best Practices

Contact