Versioning allows you to control the details of the services you interact with so you can maintain stability for your Flows even as functionality is added and modified. This document explains the different APIs you can specify versions for and how they work for your Flows. It also covers the guarantees made about support and timing for a given version.
WhatsApp Flows allows you to indicate the following versions:
Version | Type | Format | Example |
---|---|---|---|
Flow JSON | string |
|
|
Data API | string |
|
|
Message | integer |
|
|
Adapting the guidance provided by Semantic Versioning (see semver.org), version numbers adhere to the following rules:
1.9
is 1.10
(not 2.0
).1.5
leads to the release of version 2.0
), new changes will be added only to the latest major version. This means that new (non breaking) functionality will be added as version 2.1
and there will never be a version 1.6
.The following is an example timeline of changes made to an API using the {major}.{minor}
syntax, starting from an initial version of 1.0
.
Change | Version Change |
---|---|
Add a new parameter |
|
Add new non-breaking functionality |
|
Deprecate and remove functionality |
|
Add a new layout type |
|
Add a new component |
|
Breaking behavior change |
|
In the process of improving functionality and responding to external requirements, versions may be frozen or expired after their launch. To minimize upgrading effort for Flow developers, the goal is to support versions for as long as possible and provide ample notice for migration when a version's state changes.
Each version will be in exactly one of the following states at any point in time:
Active: When a version is active, you are free to create and publish Flows targeting this version. There will always be at least one active version at any given time.
Frozen: When a version is frozen, publishing a Flow that targets this version is prohibited. This means that any Flow relying on this version can no longer be created or updated as the publishing step will fail. However, existing Flows that target a frozen version are still able to be sent to customers and customers are still able to open Flows targeting a frozen version.
All versions have a best-effort target support time of 12 months total before being frozen, followed by another 12 months total before being expired. To ensure a reasonable amount of lead time to upgrade, notifications will be sent out 90 days before the change (freezing or expiring) date.
Unfortunately, circumstances may require that a version be frozen or expired before the 12 month target timeline. This means a version may be frozen or expired in less than 12 months, however the 90 day notification period will be maintained. Note that the "freezing" period may be skipped entirely in cases where a version needs to be expired as soon as possible.
There will always be at least one active (non-frozen) version even if that version has been active for 12 months.
In this example, a new major version (2.0
) is released very soon after the first release (1.0
).
This example shows what our target support timeline is for a version without any external pressure to adjust the target timelines.
Date | Event |
---|---|
1-Jan-2024 | Version |
2-Jan-2024 | Version |
30-Sep-2024 | Notice period for |
31-Dec-2024 | Version |
30-Sep-2024 | Notice period for |
31-Dec-2024 | Version |
In this example, a security vulnerability is found in a specific minor version (1.1
) requiring that the version be expired as quickly as possible to keep users safe. In this scenario, the version is never frozen, but instead skips directly to being expired for security reasons.
Date | Event |
---|---|
1-Dec-2023 | Version |
31-Dec-2023 | Security vulnerability in |
31-Dec-2023 | Version |
1-Jan-2024 | Notice period for |
31-Mar-2024 | Version |