Flows

WhatsApp Flows is a way to build structured interactions for business messaging. With Flows, businesses can define, configure, and customize messages with rich interactions that give customers more structure in the way they communicate.

You can use Flows to book appointments, browse products, collect customer feedback, get new sales leads, or anything else where structured communication is more natural or comfortable for your customers.

With Flows, you can:

• Present simple input forms (in order to schedule an appointment, for example)

• Create workflows that guide users through multiple screens (for ordering products, for example)

• Create endpoints that exchange data across screens to enable more complex interactions (such as guiding a user through a process with multiple potential outcomes)

How does it work?

Flows is a feature of the WhatsApp Business Platform that allows you to swiftly develop and deploy native, task-centric workflows on WhatsApp. This results in enhanced interactions between customers and businesses.

With WhatsApp Flows businesses can design, build and customize their own journeys, which can make chatbot and AI agent solutions better, as well as offer end-to-end experiences.

For users, Flows can improve interactions with businesses on WhatsApp, leading to better task completion and fewer drop offs than alternative channels.

For businesses, Flows can improve engagement and completion rates, resulting in improved business outcomes.

Leveraging Flows

Flows is built for form-based use cases. You can create Flows to achieve a range of tasks with your customers, including:

• Lead generation

• Appointment booking

• Registration, Sign up, and Sign in

• Customer support and feedback

• And many more

Sign Up

Appointment Booking

How are Flows configured and used?

Flows are linked from a CTA in a message. Flows are composed of:

1. Screens: When tapping on the Flows CTA in a message, the user will access the initial screen of the Flow. The user can then interact with the Flow to move through multiple screens until completion.

2. Layouts: These define how components are presented within a Flow, providing a structured look and feel.

3. Components: You can use components to display information, and to create input fields for your users. You can display information with Text, Images, and Embedded links. You can create input fields for your users to complete using Text Inputs, Dropdowns, Checkboxes, Radio Buttons, Opt-in, and Date Pickers.

Flows can be attached and sent as Business Initiated Messages, as well as standard messages. See Best Practices.

Getting Started

WhatsApp Flows are supported for numbers hosted either through Cloud API or as On-Premise API hosted by 360dialog.

Manage Flows

Manage Flows through the WhatsApp Manager

Clients can set up Flows directly from the WhatsApp Business Manager UI. To access it, the user must have admin rights to manage the account. The Flows editor can be found under the "Account tools" section under the main menu in Meta's WhatsApp Manager.

Manage Flows through the Partner API

Flows can be crafted through our Partner API. We have enabled various endpoints to perform different operations to Flows. Alternatively, your clients can access a Flow builder user interface through the "Account tools" section in Meta's WhatsApp Manager.

Meta has introduced a new flow JSON template “Book an Appointment” which you can use as reference when creating a flow in Builder. The flow template can be found here.

Creating a Flow

POST https://hub.360dialog.io/api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows

New Flows are created as drafts.

Request Body

{
  "id": "<Flow-ID>"
}

Updating a Flow

PATCH https://hub.360dialog.io/api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows/{flow-id}

Existing Flows can be updated using the update endpoint, by providing the Flow ID.

Request Body

Updating a Flow's Flow JSON

POST https://hub.360dialog.io/api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows/{flow_id}/assets

The individual screens of a Flow are defined through a "Flow JSON", that can be updated through this endpoint. To learn more about the Flow JSON definition follow this documentation link.

Request Body

{
  "success": true,
  "validation_errors": []
}

Preview a Flow

GET https://hub.360dialog.io/api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows/{flow_id}/preview

Flows can be previewed through a public link generated with this endpoint. The preview will show how the screens will look like, but will not be interactive. The final screens might render slightly different for some users.

Query Parameters

"preview": 
{
  "preview_url": "<URL>",
  "expires_at": "<timestamp>",
  "id": "<Flow-ID>"
}

Deleting a Flow

DELETE https://hub.360dialog.io/api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows/{flow_id}

While a Flow is in draft status it can be deleted. Once published a flow can only be deprecated (see endpoint documentation further down).

Retrieving a List of Flows

GET https://hub.360dialog.io/api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows

This endpoint can be used to retrieve a list of flows under a WhatsApp Business Account (WABA).

Query Parameters

{
    "data": [
    {
        "id": 1,
        "name": "flow 1",
        "status": "DRAFT"
    },
    {
        "id": 2,
        "name": "flow 2",
        "status": "PUBLISHED"
    },
    {
        "id": 3,
        "name": "flow 3",
        "status": "DRAFT"
    }
    ]
}

Retrieve Flow Details

GET https://hub.360dialog.io/api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows/{flow_id}

This endpoint will return a specified flow's details such as: id, name, status, and validation errors if they exist. You can request other fields by using the fields param in the request.

Query Parameters

{
  "id": "<Flow-ID>",
  "name": "Flow Name",
  "status": "DRAFT",
  "validation_errors": []
}

Retrieving a Flow's List of Assets

GET https://hub.360dialog.io/api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows/{flow_id}/assets

Returns all assets attached to a specified flow.

{
  "name": "flow.json",            
  "asset_type": "FLOW JSON",
  "download_url": "<DOWNLOAD-URL>",  
  "paging": {
    "cursors": {            
      "before": "QVFIU...",            
      "after": "QVFIU..."        
    }    
  }
}

Publishing a Flow

POST https://hub.360dialog.io/api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows/{flow_id}/publish

You can publish your flow once you have ensured that the Flow meets the design principles of WhatsApp Flows, the Flow complies with WhatsApp Terms of Service, the WhatsApp Business Messaging Policy and, if applicable, the WhatsApp Commerce Policy.

Once published, a flow cannot be modified. Changes to a flow can be done by cloning it and modifying the cloned copy of the Flow.

{
  "success": true
}

Deprecating a Flow

POST https://hub.360dialog.io/api/v2/partners/{partner_id}/waba_accounts/{waba_account_id}/flows/{flow_id}/deprecate

Once a flow is published, it cannot be modified or deleted, but can be marked as deprecated.

{
  "success": true,
}

Webhooks

If you're subscribed to our Partner API webhooks, you will receive events regarding the statuses and performance of your business' Flows.

Currently, there are webhooks to monitor:

• Flows status changes

• Client error rates

• Endpoint error rates

• Endpoint channel latencies

• Endpoint channel availability

Additional information on the webhook events' payloads can be found in Meta's developer documentation here.

Setup Data Channel

In order to later de- and encrypt data passed through WhatsApp Flows, every WhatsApp Business Account (WABA) requires a key pair, which needs to be signed for every phone number sending Flows within the WABA.

Generating a Key Pair

Generate a public and private RSA key pair by typing in the following command in the terminal/console within your operating system (Note: OpenSSL needs to be installed):

openssl genrsa -des3 -out private.pem 2048

The generates 2048-bit RSA key pair encrypted with a password you provided. Next, you need to export the RSA public key to a file, which can be accessed within your file system:

openssl rsa -in private.pem -outform PEM -pubout -out public.pem

Signing the Public Key

For every phone number sending Flows the public key needs to be signed. This will be done through the our WhatsApp Business API endpoints. The process differs for Cloud API and On-Premise.

Set Business Public Key (Cloud API)

POST https://waba-v2.360dialog.io/whatsapp_business_encryption

Request Body

{
  "meta": 
  {
    "api_status": "stable",
    "version": "<latest-api-version>"
  }
}

Set Business Public Key (On-Premise API) [will be deprecated]

POST https://waba.360dialog.io/v1/settings/business/whatsapp_business_encryption

Request Body

{
  "meta": 
  {
    "api_status": "stable",
    "version": "<latest-api-version>"
  }
}

Verifying the Public Key

You can verify the public key by retrieving it through the following endpoints.

Get Business Public Key (Cloud API)

GET https://waba-v2.360dialog.io/whatsapp_business_encryption

{
  "business_public_key": "<2048_bit_RSA_key>"
  "business_public_key_signature_status": VALID | MISMATCH
}

Get Business Public Key (On-Premise API)

GET https://waba.360dialog.io/v1/settings/business/whatsapp_business_encryption

{
  "business_public_key": "<2048_bit_RSA_key>"
  "business_public_key_signature_status": VALID | MISMATCH
}

Set up Data Channel Endpoint

When the Flow needs to exchange data with your backend systems, it will make an HTTP request to an endpoint, that you provide. This endpoint needs to be set up so that it can receive and process POST requests.

With this endpoint you will receive data passed into the Flow by the end user, which you can process e.g. storing it in your database.

Once set up you will share the data channel endpoint URL with the Flow through the Flow's Flow JSON.

Meta has introduced an endpoint example in NodeJS that works with the “Book an Appointment” flow JSON end to end, with app secret validation, endpoint error codes, and script to create public/private key. The endpoint code is available on Github and Glitch.

Implement Encryption/Decryption

The body of each request passed to your endpoint will be encrypted and will have the following format:

{
    encrypted_flow_data: "<ENCRYPTED FLOW DATA>",
    encrypted_aes_key: "<ENCRYPTED_AES_KEY>",
    initial_vector: "<INITIAL VECTOR>"
 }

You can then proceed to decrypt this data using the encrypted_aes_key. You can find a detailed example with sample code on this page of Meta's developer documentation.

After encryption the data will have the following format:

{
    version: "<VERSION>",
    user_locale: "<LOCALE>",
    action: "<ACTION_NAME>",         // init | back | data_exchange | ping
    screen: "<SCREEN_NAME>",
    data: {                         // JSON of values from screen
        prop_1: "value_1",
        ...
        prop_n: "value_n"
    },
    flow_token: "<FLOW-TOKEN>”
}

After processing decrypted request you can process the data end craft a response object, that will be encrypted and returned back to the Flow. A sample response payload before encryption would follow the format:

{
    eg_textfield_variable_1: "sample_Value_1",
    eg_textfield_variable_2: "sample_Value_2"
}

The response payload needs to be encrypted using the AES key received in the request and can afterwards be send back as Base64 string. An example on how to encrypt the data can be found in Meta's developer documentation via this link.

Implement Endpoint Logic

Your endpoint will receive requests in the following cases:

1. User opens the Flow

2. User submits the screen

3. User presses the back button on the screen

4. Error notification request (in case your endpoint returned with invalid content on the previous request)

5. Periodical health check from WhatsApp

For a detailed explanation of all cases and how to process the individual requests, please refer to Meta's developer documentation for implementing endpoint logic.

Webhook Response

Once the Flow closes you will receive a message payload through your messages webhook URL, which will look like the followig example:

{
  "messages": [{
    "context": {
      "from": "16315558151",
      "id": "gBGGEiRVVgBPAgm7FUgc73noXjo"
    },
    "from": "<USER_ACCOUNT_NUMBER>",
    "id": "<MESSAGE_ID>",
    "type": "interactive",
    "interactive": {
      "type": "nfm_reply",
      "nfm_reply": {
        "name": "galaxy_message",
        "response_json": {
            "flow_token": "<FLOW_TOKEN>", 
            "optional_param1": "<value1>",
            "optional_param2": "<value2>"
        }
      }
    },
    "timestamp": "<MESSAGE_SEND_TIMESTAMP>"
  }]
}

Send Flow as Message

Via WhatsApp Manager

Adm users can use the Flows Builder, which allows Flows to be sent directly via WhatsApp Manager. The functionality works only with phone numbers registered to Cloud API.

Via API

You can send a Message with a Flow in a user-initiated conversation using a Message with a Call To Action (CTA). You send this message either through the On-Prem client or Cloud API with information specific to the Flow. The Flow is triggered when the user taps the CTA button.

To send a message with a Flow, you can use the new type of the Interactive Object named flow with the following properties:

Interactive message parameters

Send a POST call to the /messages endpoint.

Sample Request for Cloud API

{
  "recipient_type": "individual",
  "messaging_product": "whatsapp",
  "to": "whatsapp-id",
  "type": "interactive",
  "interactive": {
    "type": "flow",
    "header": {
      "type": "text",
      "text": "Flow message header"
    },
    "body": {
      "text": "Flow message body"
    },
    "footer": {
      "text": "Flow message footer"
    },
    "action": {
      "name": "flow",
      "parameters": {
        "flow_message_version": "3",
        "flow_token": "AQAAAAACS5FpgQ_cAAAAAD0QI3s.",
        "flow_id": "1",
        "flow_cta": "Book!",
        "flow_action": "navigate",
        "flow_action_payload": {
          "screen": "<SCREEN_NAME>",
          "data": { 
            "product_name": "name",
            "product_description": "description",
            "product_price": 100
          }
        }
      }
    }
  }
}

Sample Response

{
  "contacts": [
    {
      "Input": "+447385946746",
      "wa_id": "47385946746"
    }
  ],
  "messages": [
    {
      "id": "gHTRETHRTHTRTH-av4Y"
    }
  ],
  "meta": {
    "api_status": "stable",
    "version": "2.44.0.27"
  }
}

Send Flow Template Message

You can send a template message with a WhatsApp Flow. Only published Flows can be sent this way. Use the new button type called FLOW. Use this type to specify the Flow to be sent with the template message.

First you need to create a template. Here is an example request:

{
  "name": "example_template_name",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "body",
      "text": "This is a flows as template demo"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "FLOW",
          "text": "Open flow!",
          "flow_id": "<flow-id>",
          "navigate_screen":  "Flows Json screen name",
          "flow_action": "navigate"
        }
      ]
    }
  ]
}'

Sample Response

{
  "id": "<template-id>",
  "status": "PENDING",
  "category": "MARKETING"
}

Now you can send a template message with a Flow using the following request:

Sample Request for Cloud API

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "template",
  "template": {
    "name": "TEMPLATE_NAME",
    "language": {
      "code": "LANGUAGE_AND_LOCALE_CODE"
    },
    "components": [
      {
        "type": "button",
        "sub_type": "flow",
        "index": "0",
        "parameters": [
          {
            "type": "action",
            "action": {
              "flow_token": "FLOW_TOKEN",   //optional, default is "unused"
              "flow_action_data": {
                 ...
              }   // optional, json object with the data payload for the first screen
            }
          }
        ]
      }
    ]
  }
}

Sample Response

{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "<phone-number>",
      "wa_id": "<phone-number>"
    }
  ],
  "messages": [
    {
      "id": "<message-id>"
    }
  ]
}

Receiving Flow Response

Upon flow completion a response message will be sent to the WhatsApp chat. You will receive it in the same way as you receive all other messages from the user - via message webhook. response_json field will contain flow-specific data. See Webhook Notifications for more details.

Sending a WhatsApp Flow as user initiated message

{
    "recipient_type": "individual",
    "to": "whatsapp-id",
    "type": "interactive",
    "interactive": {
        "type": "galaxy_message",
        "header": {
            "type": "text",
            "text": "Flow message header"
        },
        "body": {
            "text": "Flow message body"
        },
        "footer": {
            "text": "Flow message footer"
        },
        "action": {
            "name": "",
            "parameters": {
                "flow_message_version": "3",
                "flow_token": "AQAAAAACS5FpgQ_cAAAAAD0QI3s.",
                "flow_id": "1",
                "flow_cta": "Book!",
                "mode": "draft"
            }
        }
    }
}

Best Practices

Here are some guidelines to optimize both the WhatsApp Flows user and developer experience.

Form Flows

Feedback Form Flow

The Feedback Form Flow can be used to collect customer feedback for an experience that includes purchase and delivery of a product. It can also easily be modified to collect other kinds of customer feedback as well.

This example tutorial breaks out the wrapper scaffolding code from the screen code. However, you should combine all the code in these examples using the Form Builder.

Wrapper Code

Include the following code to "wrap" the 2 screens of the Feedback Form (the General Satisfaction Questions screen, and the Rating Questions screen):

{
    "version": "2.1",
    "screens": [
  /* screens we'll define in the next sections */
    ]
}

General Satisfaction Questions Screen:

{
    "id": "screen_feedback_one",
    "title": "Feedback 1 of 2",
    "layout": {
        "type": "SingleColumnLayout",
        "children": [
            {
                "type": "Form",
                "name": "form_feedback_one",
                "children": [
                    {
                        "type": "TextSubheading",
                        "text": "Would you recommend us to a friend?"
                    },
                    {
                        "type": "RadioButtonsGroup",
                        "label": "Choose one:",
                        "name": "would_recommend",
                        "data-source": [
                            {
                                "id": "1",
                                "title": "Yes"
                            },
                            {
                                "id": "0",
                                "title": "No"
                            }
                        ],
                        "required": true
                    },
                    {
                        "type": "TextSubheading",
                        "text": "How could we do better?"
                    },
                    {
                        "type": "TextArea",
                        "label": "Leave a comment",
                        "required": false,
                        "name": "how_to_do_better_comment"
                    },
                    {
                        "type": "Footer",
                        "label": "Continue",
                        "on-click-action": {
                            "name": "navigate",
                            "next": {
                                "type": "screen",
                                "name": "screen_feedback_two"
                            },
                            "payload": {
                                "would_recommend": "${form.would_recommend}",
                                "how_to_do_better": "${form.how_to_do_better_comment}"
                            }
                        }
                    }
                ]
            }
        ]
    }
}

The Form component organizes all the input fields on the page and sets the footer CTA to be disabled until all required fields have been completed.

RadioButtonsGroup and TextArea components are used to get input from the user.

Additional items to note here are the navigate action which is designed to navigate to the chosen screen. This example also passes a payload to the next screen - the form collects the would_recommend and how_to_do_better payload so it can be received as part of the user’s response.

Rating Questions Screen

Once you have the first screen in the Builder and modified as needed, the following can be pasted below it:

{
    "id": "screen_feedback_two",
    "title": "Feedback 2 of 2",
    "data": {
        "would_recommend": {
            "type": "string",
            "__example__": "1"
        },
        "how_to_do_better": {
            "type": "string",
            "__example__": "Have more color options"
        }
    },
    "terminal": true,
    "layout": {
        "type": "SingleColumnLayout",
        "children": [
            {
                "type": "Form",
                "name": "form_feedback_two",
                "children": [
                    {
                        "type": "TextSubheading",
                        "text": "Rate the following: "
                    },
                    {
                        "type": "Dropdown",
                        "label": "Purchase experience",
                        "required": true,
                        "name": "purchase_experience_dropdown",
                        "data-source": [
                            {
                                "id": "5",
                                "title": "★★★★★• Excellent (5/5)"
                            },
                            {
                                "id": "4",
                                "title": "★★★★☆• Good (4/5)"
                            },
                            {
                                "id": "3",
                                "title": "★★★☆☆• Average (3/5)"
                            },
                            {
                                "id": "2",
                                "title": "★★☆☆☆• Poor (2/5)"
                            },
                            {
                                "id": "1",
                                "title": "★☆☆☆☆• Very Poor (1/5)"
                            }
                        ]
                    },
                    {
                        "type": "Dropdown",
                        "label": "Delivery and setup",
                        "required": true,
                        "name": "delivery_dropdown",
                        "data-source": [
                            {
                                "id": "5",
                                "title": "★★★★★• Excellent (5/5)"
                            },
                            {
                                "id": "4",
                                "title": "★★★★☆• Good (4/5)"
                            },
                            {
                                "id": "3",
                                "title": "★★★☆☆• Average (3/5)"
                            },
                            {
                                "id": "2",
                                "title": "★★☆☆☆• Poor (2/5)"
                            },
                            {
                                "id": "1",
                                "title": "★☆☆☆☆• Very Poor (1/5)"
                            }
                        ]
                    },
                    {
                        "type": "Dropdown",
                        "label": "Customer service",
                        "required": true,
                        "name": "customer_service_dropdown",
                        "data-source": [
                            {
                                "id": "5",
                                "title": "★★★★★• Excellent (5/5)"
                            },
                            {
                                "id": "4",
                                "title": "★★★★☆• Good (4/5)"
                            },
                            {
                                "id": "3",
                                "title": "★★★☆☆• Average (3/5)"
                            },
                            {
                                "id": "2",
                                "title": "★★☆☆☆• Poor (2/5)"
                            },
                            {
                                "id": "1",
                                "title": "★☆☆☆☆• Very Poor (1/5)"
                            }
                        ]
                    },
                    {
                        "type": "Footer",
                        "label": "Done",
                        "on-click-action": {
                            "name": "complete",
                            "payload": {
                                "purchase_experience_rating": "${form.purchase_experience_dropdown}",
                                "delivery_rating": "${form.delivery_dropdown}",
                                "customer_service_rating": "${form.customer_service_dropdown}",
                                "would_recommend": "${data.would_recommend}",
                                "how_to_do_better": "${data.how_to_do_better}"
                            }
                        }
                    }
                ]
            }
        ]