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.
Setting it up
Section titled “Setting it up”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:
- 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).
- 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. - Write a matching handler in your own code, using that same path:
import osfrom 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_initdef 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).
The encryption key
Section titled “The encryption key”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())Two independent layers of authentication
Section titled “Two independent layers of authentication”A Flow request that reaches your code has already passed two separate checks, and both have to be right:
- 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. - Payload decryption, in your own code - the request body itself is separately encrypted with
your
business_private_key;pywadecrypts 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 yourbusiness_private_keyfirst if you see this.