WhatsApp Flows

Changelog

Updated: Nov 7, 2025
Copy for LLM

Currently Supported Versions

Purpose Flow JSON version Data API version Message version
Publishing Flows
5.1
6.0, 6.1, 6.2, 6.3
7.0, 7.1, 7.2
7.3 (Recommended)
3.0
4.0 (Recommended)
3 (Recommended)
Sending Flows
2.1

3.0, 3.1

4.0
5.0, 5.1

6.0, 6.1, 6.2, 6.3
7.0, 7.1, 7.2
7.3 (Recommended)
3.0
4.0 (Recommended)
3 (Recommended)

Release Notes

November 11th, 2025 release

Beginning in early December 2025, we will begin supporting Flows on WhatsApp Web. Users will be able to open, complete, and view Flow responses on WhatsApp Web companions. No action is required, this feature will be enabled automatically.
We are launching Data API version 4.0, which features improvements to the security of the Flows endpoints.

WhatsApp Flows Endpoints Security Enhancements (Data API Version 4.0)

  • To further protect user interactions and ensure requests are genuinely from the intended recipients, we have strengthened the security of WA Flows endpoints. Previously, the system relied on flow tokens as identifiers. While effective, we have added some improvements to the verification process.
  • We have introduced a robust two-signature authentication mechanism:
  • 1. Platform-side Signature Verification: Our platform now verifies the authorization of requests for specific flow messages. This process is handled entirely by our system and does not require any changes or action from your business.
  • 2. Flow Token Signature: Businesses now have the option to use an extra layer of authentication. This signature is generated by our system and added to the data channel request payload. This signature can be optionally used by businesses to verify that requests originate from users who received the corresponding flow message, helping ensure authenticity and security of data channel endpoints.

    • What Does This Mean for Businesses?

  • No action required for the platform-side verification; it is managed by us.
  • Optional enhancement: Businesses can choose to use the flow token signature authentication for added security (More details).
  • To enable the improvements, set the data_api_version to 4.0 in the Flow JSON.

    • September 10th, 2025 release

    Starting with 10th of September 2025 the Flow version 5.0 is frozen. Please upgrade Flows on this version to the recommended version, to avoid any disruption.
    We are releasing the latest Flow JSON version, 7.3, which includes improved Flow JSON validations.

    Flow JSON Validation Updates

    Validation for routing model and data model in Flow JSON

  • The Flow's routing model's improved validation makes sure only valid routes are used for navigation. We've also improved the validation for the screen's data model. These updates don't change how things work, but they make it easier to spot errors in the Flow JSON.

    • July 8th, 2025 release

    On 9th of September 2025 Flow version 5.0 will freeze. Please upgrade Flows on this version to the recommended version, to avoid any disruption.
    We are releasing the latest Flow JSON version, 7.2, with improvements to the Flow JSON validations.

    Component Updates

    Validation for nested expressions in Flow JSON actions

  • Nested expressions used in actions are now validated to ensure referenced variables in the data model exist. This doesn't add any functional change, but makes it easier to spot errors on Flow JSON.

    • June 10th, 2025 release

    On 9th of September 2025 Flow version 5.0 will freeze. Please upgrade Flows on this version to the recommended version, to avoid any disruption.
    We are releasing the latest Flow JSON version, 7.1, with a new component and several enhancements.

    Component Updates

    Update to the ChipsSelector component

  • We are updating the ChipsSelector component to align its behaviour with other list selection components (i.e. CheckboxGroup, RadioButtonsGroup and Dropdown). The ChipsSelector component can now:
  • Be used inside If/Switch components
  • Have "on-select-action" and "on-unselect-action" properties defined at its root.

    • Image Carousel component

  • The Image Carousel component allows users to slide through multiple images.

    • April 8th, 2025 release

    Starting April 8th, 2025 Flow versions 2.1, 3.0, 3.1 and 4.0 are now frozen. Please upgrade Flows on these versions to the recommended version, to avoid any disruption.

    Message Template Updates

    Flows can now be sent with other buttons in message templates

  • You can now send message templates with a Flow and other types of buttons as part of the same message.
  • An icon can now be selected for different types of Flows, and a default icon will be displayed if none is selected. This will not affect templates that have already been sent.
  • You can create message templates from WhatsApp Manager⁠ or directly via API.

    • March 11th, 2025 release

    Flow JSON version 7.0 is now available with component improvements.

    Component updates (Flow JSON Version 7.0)

    New property "label-variant" on TextArea and TextInput

  • You can now utilize the label-variant: 'large' attribute to display a large label on TextArea or TextInput components. This feature allows the label to be positioned above the input field, accommodating up to 4 lines of text for improved readability and user experience.

    • Update to on-select-action behaviour

  • In Flow JSON version 6.0, we introduced a breaking change that triggered the on-select-action at the component level when a new screen was rendered. This same functionality is present in Flow JSON versions 6.1, 6.2, and 6.3.
  • Reversion of this Change: We are reverting this change in Flow JSON version 7.0. From this version onwards, if an on-select-action is present on the component level, it will not be triggered when a new screen is rendered. This behavior is identical to that of Flow JSON versions 5.1 and older.

    • Form validations introduced for init-values and error-messages

  • We've introduced type checking for init-values and error-messages properties in the Form component. This ensures that values match the expected types where they're used.
    For example, a TextInput with input-type="number" will only accept numeric init-values. Non-numeric values will trigger an error message.

    • January 14th, 2025 release

    We are releasing the latest Flow JSON version, 6.3, with a new component and tooling improvements.

    Component updates (Flow JSON Version 6.3)

    Chips Selector component

  • The Chips Selector component simplifies tasks, such as selecting preferences or time slots, by presenting options in a compact and interactive format.

    • Footer supported with RichText component

  • The RichText component can now be used in conjunction with the Footer component on the same screen, allowing the Flow to navigate from or end at a screen that includes RichText.

    • Developer tooling improvements

    We have simplified some of our Flow APIs, so they are easier to create and send:

    Published Flow can be created in a single API call

  • We have added two new optional parameters (flow_json, publish) to Create Flow API call, which allow the caller to provide the Flow JSON and publish the new Flow immediately. Previously, at least three API calls were required (Create Flow, Update Flow JSON, and Publish Flow).

    • Simplified send Flow API call

  • We have decreased number of required parameters for sending a Flow. The caller now only needs to specify flow_message_version, flow_cta and flow_id/flow_name. The rest of the parameters are now optional.

    • Simplified creation of message template with a Flow

  • Similar as above, we have decreased number of required parameters for creation of message template with a Flow. Only text, and flow identifier flow_id/flow_name/flow_json need to be provided for Flow button. The rest of the parameters are now optional.

    • December 10th, 2024 release

    We are releasing a new Flow JSON version with a new component and several tooling improvements.

    Component updates (Flow JSON Version 6.2)

    NavigationList component

  • The Navigation list offers a user-friendly way to explore multiple options within a Flow. Each list item enables navigation and can display a range of content, including text, images, and tags, making it easy for users to move between different screens in the Flow.

    • Regular expressions supported in TextInput component

  • Introduced a new pattern property to enable regular expression validation for text inputs with input-type as text, password, passcode and number.

    • Developer tooling improvements

    We are also adding some features to the API, and making some of those available on the Builder:

    Published Flows can be edited from the Builder

  • All new Flows could be edited from the API since November, and now they can also be edited from the Flows Builder on WhatsApp Manager. This enables changes to be made directly within the same Flow, allowing messages to be sent with the updated content using the same Flow ID, eliminating the need to recreate the Flow.

    • API to migrate (copy) Flows from one WABA to another

  • Flows can be migrated from one WhatsApp Business Account (WABA) to another owned by the same business. Migration doesn't move the source Flows, it creates copies of them with the same names in the destination WABA. The migration API is documented here and included in the Flows API Postman collection.⁠

    • Endpoint encryption examples in C# & Go

  • We added example code for Flows endpoint in C# here⁠ and in Go here.⁠

    • Flow previews can be shared from the Builder

  • A new share button will generate the preview URL without the need to use the existing API, so it can be shared with other users and embedded as an iframe into other applications.

    • New Flow JSON deprecation webhooks

  • Introducing new webhooks when the Flow version is about to be frozen or expired. These warning will also be visible on the Builder.

    • November 12th, 2024 release

    We are releasing 2 new Flow JSON versions, alongside some exciting tooling improvements:

    Component updates (Flow JSON Version 6.1)

    CalendarPicker component

  • New component that allows users to select a single date or a range of dates from a more user-friendly full calendar view making it easier to navigate dates and visualize date availability.

    • Flow JSON Version 6.0

    Version 6.0 introduces three backwards incompatible changes:
  • String values in component properties can't be empty. Previously values such as "", " ", "\n", "\t", "\n" were accepted; from version 6.0 these are no longer valid.
  • Maximum image size for list components (Checkbox Group, Radio Buttons Group, Dropdown) is reduced from 300KB to 100KB.
  • If on-select-action is present on the component level, it will be triggered when the new screen is rendered, whether via cache or back-and-forth navigation.

    • This new version is fully available now, and introduces the following new features:

    Nested Expressions and string concatenation in component properties

  • Boolean expressions and string concatenation can now be used in component properties. Expressions can combine static and dynamic data.

    • New update_data action

  • A new action has been added to support dynamic updates of the current screen based on user interactions. This action can be used to update elements on the same screen in response to user inputs, handle dynamic data relationships, promote reusable templates, and more.

    • New on-unselect-action property

  • A new property has been added to several components that works similarly to the existing on-select-action but will allow changes made by the update_data operation in the on-select-action to be reverted.

    • OptIn and EmbeddedLink can now open external links

  • A new action open_url can be used in on-click-action to open external links in Flows from EmbeddedLink and OptIn components. These external links will open in the device's default browser.

    • Developer tooling improvements

    We are introducing a new page within the Builder, and improvements to the API and onboarding through the UI:

    Business insights

  • Statistics on how consumers interact with your Flows can now be found on the builder on published Flows. These metrics help track Flow performance and reveal usage trends, including the count of user interactions with Flows.

    • Published Flows can now be edited

  • All new Flows can be edited by updating their metadata or Flow JSON via API, even after they have been published. This enables changes to be made directly within the same Flow, allowing messages to be sent with the updated content using the same Flow ID, eliminating the need to recreate the Flow.

    • Simplified Flows onboarding

  • All businesses can now start creating and building Flows. To send and publish a Flow, business verification and high message quality are still required.

    • October 8th, 2024 release

    We are adding some tooling improvements to both the API and Flows Builder.

    Flows can be referenced by name using the API

  • Flow messages can be sent using the Flow's name instead of its ID, which is useful when you have clones of the same Flow in multiple WhatsApp Business Accounts with different Flow IDs.
  • You can also create a message template with a Flow using the Flow's name.

    • Flow JSON can be used when creating Message Templates through the API

  • It is now possible to provide Flow JSON as part of the request payload when creating Message Templates with a Flow attached, so you don't need to create and publish a Flow as a previous step.

    • Endpoint setup on Flows builder has a dedicated section

  • Flows with endpoint can be configured on a dedicated tab at the bottom of the Flows builder. Other endpoint-related features can also be found there, such as snippets and links to the documentation.

    • September 16th, 2024 release

    New Flow JSON version - 5.1

    We are introducing a new Flow JSON version which contains a new component and several enhancements.

    RichText component

  • You can use this component to render text with rich formatting options. The following markdown syntax is supported:
    • - Heading and Subheading
    - Text formatting (italic, bold, strikethrough)
    - Basic lists
    - Links
    - Images
    - Tables

    TextBody and TextCaption can use markdown

  • A new property "markdown" can be used with both components, which allows to use a subset of the RichText capabilities.

    • Flow termination message has a new look

  • SMBs are now able to view the responses received for Flows completion and download them in CSV format. Consumers will soon also be able to view the information submitted when completing the Flow.
  • In Flow JSON, certain fields can now be marked as "sensitive" so that data for those fields is not visible as part of the response details displayed to the user.

    • Developer tooling improvements

    We are making it easier to preview Flows and integrate into existing websites.

    Web preview now can be used in interactive mode and inside an iframe

  • The preview URL can be configured with new parameters to make it interactive and show a debug panel. It works with Flows with and without an endpoint.
  • It can also be embedded as an iframe, so it can be integrated into an existing website.

    • Flows data endpoint improvements

  • We have increased the payload limit of the Flows data endpoint to 10MB, allowing for the transmission of multiple images to screens using list (RadioButtonsGroup, CheckboxGroup, Dropdown) and RichText components.

    • August 13th, 2024 release

    New Flow JSON version - 5.0

    We are introducing a new Flow JSON version which contains several enhancements. This is the recommended version to use if you are creating a new Flow.
    Upgrading Flows to version 5.0 from 4.0: Version 5.0 introduces a backwards incompatible change:
    • All DatePicker components now receive and set dates in “YYYY-MM-DD” format, which makes the values unrelated to time zones (more details).
    No additional changes are required to port a Flow from version 4.0 to 5.0, which will unlock your access to the following new functionality:

    Images and colors are now available in Pickers

  • Added support for displaying images and colors in list components (RadioButtonsGroup, CheckboxGroup, Dropdown).

    • Media upload components: Increased limit for the number of media files sent as part of the response message

  • It is now possible to have up to 10 media files sent as part of the response message, with the combined size of all files up to 100MB.

    • Developer tooling improvements

    We are introducing a few improvements to help developers onboard and debug Flows with endpoint.

    New health status endpoint for Flow Graph API

  • It is now possible to query flow health status using new health_status field and get status of Flow health and other related entities like WABA, Business which are involved in message sending (more details).

    • New templates and development guides

  • We've added new refined templates in Flows Builder with dedicated development guides and endpoint templates ready to use.
  • You can find them under the Flow creation screen on WhatsApp Manager, or following the links below:
  • Pre-Approved Loan
  • Health Insurance
  • Personalised offer
  • Purchased Intent

    • Improved error details for Flows with endpoint

  • More detailed errors when using an endpoint are displayed on draft mode on mobile, and on the Builder in WhatsApp Manager to help with debugging.

    • July 9th, 2024 release

    Endpoint health check debugger

    • You can now check the status of the endpoint of your Flow with this new health check validator, which allows easy troubleshooting of any issues with encryption or health check requests.
    • You can find it on the endpoint setup modal within the Flows Builder in WhatsApp Manager.

    Actions debugger

    • A new panel is added to the existing Flows Builder in WhatsApp Manager, which allows viewing the data exchanged between the Flow and the Flow’s endpoint and the data passed between screens when navigating.
    • You can find it at the bottom of the editor within the Flows Builder in WhatsApp Manager.

    June 11th, 2024 release

    New Flow JSON version - 4.0

    We are introducing a new Flow JSON version which contains several enhancements (described in detail below). You can now create new Flows with this version to leverage the new functionality.
    Upgrading Flows to version 4.0 from 3.1: Version 4.0 introduces two minor backwards incompatible changes, which means you may need to make some tweaks after cloning an existing version 3.1 Flow. Specifically:
  • All CheckboxGroup and RadioButtonsGroup components now require a label property (previously optional)
  • The name property for all input and selection components cannot be empty. Previously values such as "", " ", "\n", "\t", "\n" were accepted; with version 4.0 these are no longer valid.

    • No additional changes are required to port your version 3.1 Flow to version 4.0, which will unlock your access to the following new functionality:

    [Component] Image and Document upload

  • New PhotoPicker and DocumentPicker components. These components allow users to share images and documents, respectively, within a Flow, leveraging the existing and familiar WhatsApp UX.

    • [Component] Group components label improvements

  • The CheckboxGroup and RadioButtonsGroup components now support a higher character limit for the label property, and additionally support a new description property, which can be used to provide more information to users about the selection options.

    • [Comoponents] Conditional Component Rendering

  • You can now show/hide components, based on user input or Business data, without the need to trigger a data_exchange to your Flows Endpoint, by leveraging the If and Switch Components within the Flow JSON.

    • [Flow JSON Capabilities] Global Dynamic Data Access

  • You can now reference Form and dynamic data from any screen in the Flow JSON using global accessor syntax. This means you no longer need to explicitly propagate data from screen-to-screen.

    • [Flow JSON Capabilities] Optional Form

  • The use of the Form component is now optional. This means that you can access user-entered data without the need to wrap your components inside a Form component.

    • Developer Tooling Improvements

    We are introducing several improvements to help developers onboard and use Flows.

    [Developer Tools] Improved Flows Preview in the WhatsApp Manager Builder, and in Developer Docs

  • Better/snappier preview loading and saving performance.
  • Ability to simulate iOS and dark theme modes.
  • Mobile-like bottom sheet experience within the Flows Builder editor, which displays Flow JSON error(s).

    • [Developer Tools] Update Application linked to a Flow through the Flows API

  • Added an optional application ID parameter to the Update Flow API request.

    • [Developer Tools] Send-Time validation of the screen name in "navigate" action

  • Added validation of the screen parameter in the message payload at Flow message send time if the action is navigate: invalid screens (i.e. screens that are no defined in the Flow JSON, or screens which cannot act as a first screen) will be rejected, and an API error will be returned.

    • Improved Flows experience for users

    We are releasing several improvements to the UX of Flows. These changes are not tied to a Flow JSON version; that is, they will apply to any Flows being actively sent.

    Progress Indicator

  • We have introduced a new feature to visually inform users about how much progress is left to complete the Flow. This is applicable for any Flows with more than one screen.

    • Text Truncation improvements

  • Optimized the character limit strategy for components to maximize the amount of content displayed based on device resolution.

    • Stopping WhatsApp Flows Support on Android OS 5.x.x

    As announced in May, we have now stopped support for Flows on Android devices running OS 5.x.x and older. This means that Flow messages sent to users on such devices will not be delivered, and you will receive a webhook containing a "Message Undeliverable" error. For more details on this error, please refer to the error codes documentation.

    May 2024 release

    Deprecating data_channel_uri

    • v18.0 / Forward: New field endpoint_uri will be returned.
    • v17.0 / Backwards: Old field data_channel_uri will be returned.

    Stopping WhatsApp Flows Support on Android OS 5.x.x

    • Starting June 11th, 2024, WhatsApp Flows will only be supported on Android OS 6.0 and newer versions. This means that businesses will no longer be able to send Flow messages to users with Android OS 5.x.x devices and will receive a webhook containing a “Message Undeliverable” error when trying to do so. For more details on error, please refer to the error codes.
    • Additionally, starting from July 9th, 2024, users on Android OS 5.x.x devices will no longer be able to interact with any existing Flow messages.

    April 2024 release

    Support the Optin component in the Flows UI builder

    • Extend the support of the opt-in component in the Message Templates in Flows UI editor to allow users to add and modify an additional “Read More” screen.
    • This feature enables you to display additional information (e.g., terms and conditions) on a separate screen instead of cluttering the main Flow screen. This would improve the user experience and simplifying the Flow creation process.

    March 2024 release

    • Adds a new screen for creating flow. The users can now interact with the template before using it for creating a flow.

    Exposing “UpdatedAt” field

    • New field “UpdatedAt” exposed for the GraphAPI endpoints.
    • The field is updated for every flow when name, status, flow json, etc. changes.
    • The field is returned with the GraphAPI endpoint and used on the WA Manager -> Flows page.

    BugFix- “form_name” will be removed from business paylaod

    • Bug fix for Android implementation where ‘form_name’ was unintentionally included in payload. If businesses are using this, then they may need to modify server implementations for a more sustainable setup.

    February 2024 release

    Details page

    • Introduce a new details page that provides a clear overview of Flow endpoint performance, with data on availability, latency, requests, and errors.
    • This page is available for published Flows with endpoint from the Flows Builder in WhatsApp Manager.

    Monitoring API

    • Introduce a new GraphAPI field in WA Flow object named “metric” which allows businesses retrieving a set of endpoint related metrics.

    Send Flow via WhatsApp Manager

    • Introduce a new feature in the Flows Builder that allows Flows to be sent directly via WhatsApp Manager. The functionality works only with phone numbers registered to Cloud API.

    New flow template: appointment booking template

    • Add a new flow JSON template “Book an Appointment” which can be used when creating a flow in Builder. The flow template can be found here.
    • Add an endpoint example in NodeJS that works with the “Book an Appointment” flow JSON end to end. The endpoint code is available on Github⁠ and Glitch⁠.
    • Enhance the endpoint example on Github⁠ and Glitch⁠ to include app secret validation, endpoint error codes, script to create public/private keys, and other improvements.

    January 2024 release

    Introduces support for Flow JSON version 3.1

    • Adds optional property ‘success’ for terminal screens to indicate whether terminating on that screen results in a successful flow completion.
    • A new field ‘endpoint_uri’ has been introduced and should be used instead of deprecated ‘data_channel_uri’.

    API changes

    December 2023 release

    Adds an end-to-end example for an endpoint server in Node.js that can be edited online on Glitch. The source code is also available on Github⁠.

    Introduces support for Flow JSON version 3.0

    • Removes the “data_channel_uri” property from Flow JSON
    • Introduces ability to specify Flow endpoint via API or WhatsApp Manager.

    WhatsApp Manager changes

    • Adds additional filtering options (by ID and status) on the listing page of Flows
    • Adds support for deleting and deprecating Flows
    • Adds the ability to clone Flows

    Flows in Message Templates

    • Adds support for attaching images when creating and attaching Forms in Message Templates
    • Adds new custom form starter template when creating and attaching Forms in Message Templates

    API changes

    October 2023 release

    Initial release of the WhatsApp Flows.
    Introduces support for Flow JSON version 2.1
    Introduces support for Data Api version 3.0