Versioning

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.

Overview

WhatsApp Flows allows you to indicate the following versions:

1. Flow JSON version controls the implementation and parameters used with Flow components and layouts.
2. Message version allows you to set the version for the message payload.
3. Data API version indicates which API you want to use for encryption and payload format for your endpoint (only applicable for endpoint Flows).

Version Formats

Major vs Minor Versions

Adapting the guidance provided by Semantic Versioning (see semver.org), version numbers adhere to the following rules:

1. Major versions are incremented whenever there is a "breaking change". A "breaking change" is one where existing code will not function as expected given the same inputs as before (e.g., a field being removed or functional behavior being altered).
2. Minor versions are incremented for any other material change where existing inputs continue to function as expected (e.g., adding new paremeters or functionality that does not affect existing behavior).
3. Later versions (higher version numbers) will include all features and functionality present in previous versions unless explicitly marked as deprecated.
4. Version numbers are incremented separately, not as a single decimal number. For example the version after 1.9 is 1.10 (not 2.0).
5. After a major version increase (e.g., a breaking change to 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.

Example Timeline

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.

Version Support and Lifecycle

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.

States

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.

• Expired: When a version is expired, it is no longer able to be sent to customers, and any Flows targeting an expired version are no longer able to be opened by the customer.

Target Support Schedule

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.

Examples

Target Support Timeline

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.

Reduced Timeline Due to Security Vulnerability

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.