Add a version

POST 
/v1/flows/:flow_id/versions

Adds a version of the flow from Flow JSON. 202 with the version pending while WhatsApp processes it; poll it. Identical Flow JSON to a version that is pending, in draft or failed answers 200 with that version as it is now, so a deploy script that runs twice creates nothing — except for a version that failed before WhatsApp ever saw the document, which is resumed instead: 202, the same version, pending again. A document rejected by WhatsApp ends failed with failure_reason; post a corrected document as a new version. A version already published or deprecated is never reused. Bodies up to 5 MB. Idempotency-Key is accepted. Requires the flows:write scope.

Request

Responses

200

Nothing was created. Either the flow already has a version with this exact Flow JSON, and this is that version as it is now; or this is a replay of an earlier completed request with the same Idempotency-Key and body, carrying Idempotent-Replayed: true and the bytes of that first response.

Response Headers

Idempotent-Replayed

true on a replay; absent when the document simply already existed.

202

The new version, pending while WhatsApp processes the document.

400

A malformed flow_id (code: invalid_parameter), an unrecognised query parameter (code: unknown_parameter), or an Idempotency-Key that is not 1–255 printable ASCII characters (code: invalid_parameter).

401

Missing, malformed, unknown, revoked, or expired key — one body for all of them (code: unauthorized), with WWW-Authenticate: Bearer realm="hop".

403

The key lacks the scope (code: insufficient_scope), named in WWW-Authenticate: Bearer error="insufficient_scope", scope="…".

404

No such flow — nonexistent, or another organisation's.

409

code: in_flight — an earlier request with this Idempotency-Key is still being processed, or took the key over after this attempt stalled. Retry shortly with the same key.

413

code: request_too_large — the body exceeded 5242880 bytes (5 MB). The detail states the limit and, when the request carried Content-Length, the bytes sent.

415

code: unsupported_media_type — the body was not application/json.

422

code: validation_failed — an unknown or invalid field — no_number_configured (neither the flow nor your organisation has a WhatsApp number), or idempotency_key_reuse.

429

Over a bucket. Obey Retry-After (seconds); RateLimit-* fields are informational.

Response Headers

RateLimit-Limit

Requests allowed in the current window. Informational.

RateLimit-Remaining

Requests left in the current window. Informational.

RateLimit-Reset

Seconds until the window resets. Informational.

Retry-After

Seconds to wait before retrying. The binding contract.