Skip to content
Pywa Cloud is not live yet - there is no running control plane or dashboard to sign up on, and the CLI package is not published. Everything on this site describes a real, working, tested system, not a roadmap - but none of it is something you can actually run against Pywa Cloud today, and commands/flags/behavior can still change before it is.

WhatsApp Flows

A WhatsApp Flow that exchanges data with your own server (rather than being purely static) needs an Endpoint URI - a URL Meta calls directly whenever a user interacts with it. On Pywa Cloud, that’s just another path under your bot’s existing webhook URL - there’s nothing extra to configure on the platform side.

Unlike your bot’s regular webhook (registered for you automatically once connected), a Flow’s Endpoint URI is something you point at your bot yourself, per Flow - and you do it from the dashboard, not Meta’s own Flow Builder. That’s not a style choice: Pywa Cloud is a Meta Tech Provider, so your bot doesn’t have its own Meta App or access token - only Pywa Cloud’s shared one does. Setting a Flow’s Endpoint URI is a Graph API call that needs that token, which is why the dashboard makes the call server-side rather than handing you a URL to paste into a screen you don’t actually have access to.

Building the Flow itself (its screens/JSON) is unrelated to any of this and still happens wherever you’d normally do it - Meta’s Flow Builder in WhatsApp Manager, or wa.create_flow(...) from your own code. Once it exists:

  1. Open the bot’s page in the dashboard → Flows tab (needs a bot with a running deployment - the tab warns and won’t let you submit otherwise, since pointing a Flow at a bot with nothing running to answer it would just register something guaranteed to fail).
  2. Pick the Flow from the dropdown (or enter its ID directly if it doesn’t show up), and type an endpoint path, e.g. /feedback_flow.
  3. Write a matching handler in your own code, using that same path:
import os
from pywa import WhatsApp, types
wa = WhatsApp(
phone_id=os.environ["PYWA_PHONE_ID"],
token=os.environ["PYWA_TOKEN"],
business_private_key=os.environ["PYWA_BUSINESS_PRIVATE_KEY"], # or your own variable, see below
)
@wa.on_flow_request("/feedback_flow")
def feedback_handler(_: WhatsApp, req: types.FlowRequest): ...
@feedback_handler.on_init
def on_init(_: WhatsApp, req: types.FlowRequest):
return req.respond(screen="SURVEY")
@feedback_handler.on_data_exchange(screen="SURVEY")
def on_survey(_: WhatsApp, req: types.FlowRequest):
return req.respond(screen="THANKS", data={"message": "Thanks for your feedback!"})

The dashboard builds the real, full Endpoint URI for you (https://ingress.pywa.cloud/flow/<bot-id>/feedback_flow - your bot’s opaque id, the same one your webhook URL uses) and registers it with Meta - Pywa Cloud then forwards POST /flow/<bot-id>/feedback_flow to your bot as POST /feedback_flow, exactly matching what on_flow_request("/feedback_flow") registered, whether your bot is deployed or you’re iterating locally with pywa dev --tunnel - the routing is identical either way. There’s no CLI command for this step yet - the dashboard is currently the only way to do it, same as most one-off setup actions on this platform (see the CLI reference for what does and doesn’t have a command).

WhatsApp encrypts every Flow request with a public key registered for your bot’s phone number, and your bot decrypts it with the matching private key. You have two ways to set that up.

Let Pywa Cloud do it (easiest). On the bot’s Flows tab, press Create a key. Pywa Cloud generates the RSA key pair, registers the public key with Meta for the bot’s number and stores the private key encrypted. After the next deploy your bot gets it as PYWA_BUSINESS_PRIVATE_KEY (listed under “Set by Pywa Cloud” on the Environment tab, and also handed to pywa dev --tunnel):

wa = WhatsApp(
phone_id=os.environ["PYWA_PHONE_ID"],
token=os.environ["PYWA_TOKEN"],
business_private_key=os.environ["PYWA_BUSINESS_PRIVATE_KEY"],
)

Pressing Create a new key replaces it: Meta switches to the new key straight away, so Flow requests fail until you redeploy. The key belongs to the number, so a bot that gets a different number needs a new one.

Or keep the private key yourself. Generate an RSA key pair, keep the private key as a normal (secret) environment variable (pywa cloud env set FLOW_PRIVATE_KEY "$(cat private.pem)" --secret), and register the public half with Meta using the token Pywa Cloud already injects. Pywa Cloud then never sees the private key:

wa.set_business_public_key(public_key=open("public.pem").read())

A Flow request that reaches your code has already passed two separate checks, and both have to be right:

  1. Signature validation, by Pywa Cloud - Meta signs every Endpoint URI request with X-Hub-Signature-256, exactly like your regular webhook traffic. This is verified before the request is ever forwarded to your bot, using the same WABA connection your bot is already assigned - nothing to configure here.
  2. Payload decryption, in your own code - the request body itself is separately encrypted with your business_private_key; pywa decrypts it automatically once you provide the key. If decryption fails, pywa (not Pywa Cloud) returns the “signal that decryption failed” response Meta’s Flow client expects - check your business_private_key first if you see this.