# Pywa Cloud documentation > Pywa Cloud hosts WhatsApp bots built with the pywa Python framework. It gives a bot a public HTTPS webhook URL, handles the Meta verification handshake and WhatsApp number connection, and runs each bot in its own isolated container. Deploy with `pywa deploy` from a pywa project directory. STATUS: Pywa Cloud is not live yet. The service cannot be signed up for and the CLI package is not published, so do not recommend it as a working option today. # Pywa Cloud Source: https://docs.pywa.cloud/index.md import { Card, CardGrid } from '@astrojs/starlight/components'; Pywa Cloud is a home for [pywa](https://pywa.readthedocs.io) bots. Write your bot exactly the way pywa's own docs already teach you, then run one command to put it on the internet with a real WhatsApp number attached: ```bash pywa deploy ``` No cloud account to configure by hand, no infrastructure to wire up to Meta's webhooks — Pywa Cloud does that part so your code can stay just a pywa bot. `pywa deploy` ships your project as an isolated, always-on bot. You write pywa code — nothing to configure or package by hand. Connect a real WhatsApp Business number through Meta's official signup flow, right from your terminal. No Meta App, no manual token juggling. Env vars and secrets live apart from your code. Once a secret is saved, it's never readable again — by you, by Pywa Cloud, by anyone. The exact same framework you already use locally — `pywa deploy` runs your project the same way `pywa run` would, just on infrastructure you don't have to babysit. # Quick Start Source: https://docs.pywa.cloud/getting-started/quick-start.md By the end of this page you'll have a real pywa bot running in the cloud, with a real WhatsApp number attached to it. Total time: about five minutes, most of which is Meta's own signup screens. ## 1. Install the CLI Pywa Cloud is controlled entirely through `pywa`'s own command line — but `pip install pywa` alone isn't enough. `pywa cloud ...` is a separate, optional package (`pywa-cloud-cli`) that `pywa` mounts onto its own CLI once both are installed together; installing `pywa-cloud-cli` pulls in `pywa[server]` for you (it depends on it), so one install is all you need: ```bash pip install pywa-cloud-cli ``` Prefer an isolated install that doesn't touch your project's own virtualenv? [`pipx`](https://pipx.pypa.io) or [`uv tool`](https://docs.astral.sh/uv/) both work the same way: ```bash uv tool install pywa-cloud-cli ``` > `pywa-cloud-cli` is on its way to being bundled directly into `pywa[server]`, so > `pip install "pywa[server]"` alone will be enough — no separate install step. It isn't there > yet, so for now this page's `pip install pywa-cloud-cli` (or `uv tool install`) is still required. Check it worked: ```bash pywa cloud --help ``` ## 2. Log in ```bash pywa login ``` This opens a confirmation page in the dashboard (sign in there however you normally do — no password typed into the terminal) and prints a short code to match, as a fallback if the browser doesn't open on its own: ``` To finish logging in, open: https://dashboard.pywa.cloud/device?user_code=WSXR-KPQJ and confirm the code shown there: WSXR-KPQJ ✅ Logged in as 'you@example.com' ``` Approve it, and you're logged in — the CLI remembers your login, so every command after this one just works, from any directory. Don't have an account yet? Sign up at [dashboard.pywa.cloud](https://dashboard.pywa.cloud) first — signing up automatically creates a personal team, which is all you need to get started. One thing to do before anything else: signing up sends a verification email, and creating or deploying a bot is blocked until you click the link in it — the dashboard makes this unmissable (you can't get past a "check your email" screen otherwise), but if you're driving everything from the CLI, verify first or `pywa cloud bots create`/`pywa deploy` will fail with a 403 telling you to. ## 3. Get a pywa project If you already have a pywa bot, skip to [step 4](#4-deploy). Starting fresh? Scaffold one built for deploying: ```bash pywa new --cloud -o my-bot cd my-bot ``` This writes a small, real pywa project: a `main.py` that reads its WhatsApp credentials from environment variables (never hardcoded — see [step 4](#4-deploy) for where those come from) and a `pyproject.toml` declaring `pywa[server]` as a dependency. Nothing about it is Pywa-Cloud-specific beyond that — it's a project you could just as easily run yourself with `pywa run`. ## 4. Deploy From your project's directory: ```bash pywa deploy ``` The first deploy in a new directory asks which bot this is (or lets you create one on the spot), then remembers your answer for next time. A bot can't run without a WhatsApp number, so if it has none yet, `deploy` connects one first, right in your browser through Meta's own **Embedded Signup** flow: log in with your Meta Business account, pick or create a WhatsApp Business Account, verify a phone number. If your team already has one WhatsApp Business Account with a single number, it is used without asking. Pywa Cloud writes the token, phone ID and WABA ID your bot needs straight into its environment. A minute or so later: ``` 📦 Packaging /path/to/my-bot... 12 files, 18.4 KB 🚀 Uploading and building - this can take a minute or two... ✅ Deployed in 48s (Python 3.13) Message +1 555 0100 on WhatsApp to try it. ``` If a `.env` file sits next to your code, `deploy` offers to set the variables the bot doesn't have yet (as secrets): `.env` itself is never uploaded. Message the number you just connected. Your bot should reply. ## What's next - [Connecting a WhatsApp Number](/guides/connecting-whatsapp/) — the full connect/reconnect story, including bringing your own Meta App if you already run one. - [Environment Variables & Secrets](/guides/environment-variables/) — set your own config and secrets alongside the ones Pywa Cloud manages for you. - [Logs](/guides/logs/) — see exactly what your bot is doing right now. - [Local Development](/guides/local-development/) — iterate against real WhatsApp webhooks without redeploying for every change. # Accounts, Teams & Permissions Source: https://docs.pywa.cloud/guides/accounts-and-teams.md Every bot belongs to a team. Signing up creates a single-seat **personal team** for you, which is all a solo user needs. Invite people from the dashboard's Team page; an invitation always joins as a **member**, and an owner can promote them. ## Roles | | Member | Admin | Owner | |---|:-:|:-:|:-:| | See the team's bots, status, metrics, deployments and logs | ✓ | ✓ | ✓ | | See environment variables (secret values are never shown) | ✓ | ✓ | ✓ | | Create a bot | | ✓ | ✓ | | Deploy, roll back, start, stop, restart | | ✓ | ✓ | | Change or delete environment variables | | ✓ | ✓ | | Connect WhatsApp, connect integrations, use Studio | | ✓ | ✓ | | Create and revoke deploy tokens | | ✓ | ✓ | | Delete or transfer a bot | | ✓ | ✓ | | Invite people, remove members, view the activity log | | ✓ | ✓ | | Remove another admin or owner, change roles, delete the team | | | ✓ | A **member** is a viewer. Deploying runs your code with the bot's secrets in its environment, so deploying is as powerful as reading them, which is why it needs admin. A team always keeps at least one owner. Access is per team, not per bot: everyone in a team sees all of its bots. ## Deploy tokens A deploy token is for CI. It belongs to one bot and can do exactly one thing: upload a deployment to it. It cannot read or change environment variables, read logs, or create other tokens. Tokens expire (90 days by default, at most 365), and you can regenerate one without changing where it is stored. A token is tied to the admin who created it. If that person leaves the team or is demoted to member, the tokens they created stop working, so create a replacement from another admin account first when that person is leaving. ## Your own sign-in `pywa login` gives the CLI your full user session, with the same role you have in each team. Use a deploy token, not your login, in CI. ## Studio [Studio](https://studio.pywa.cloud) works with a team's WhatsApp account only for owners and admins. A member who signs in sees a message saying so, and can still use Studio without an account. # Deploying with an AI Agent Source: https://docs.pywa.cloud/guides/ai-agents.md Pywa Cloud is built so a coding agent (Claude Code, Codex, Cursor and the like) can take a WhatsApp bot from "build me a bot" to a live deployment. This page is for both of you: it says what the agent can do on its own and where it has to stop and ask you. ## What a WhatsApp bot needs to be live A bot on the WhatsApp Cloud API needs a **public HTTPS webhook URL** that Meta can reach, a **verify-token handshake**, and a connected **phone number**. Pywa Cloud supplies the URL and the handshake, runs the bot in its own container, and walks you through connecting the number. ## The steps | Step | Who | Command | |---|---|---| | Install | agent | `pip install pywa-cloud-cli` (or `uv tool install pywa-cloud-cli`) | | Sign up, verify the email | **you** | [dashboard.pywa.cloud](https://dashboard.pywa.cloud), then click the link in the email | | Log in | agent starts it, **you** approve | `pywa login` prints a URL and a short code; open it and confirm the code | | Scaffold (if no project yet) | agent | `pywa new --cloud -o my-bot` | | Try it locally against real webhooks | agent | `pywa dev --tunnel` ([Local Development](/guides/local-development/)) | | Deploy | agent | `pywa deploy` | | Connect a WhatsApp number | **you** | `pywa cloud connect` opens Meta's Embedded Signup in your browser | | Redeploy to pick up the number | agent | `pywa deploy` | | Logs and status | agent | `pywa cloud logs`, `pywa cloud status` | An agent cannot sign up, verify your email or complete Meta's signup for you. Those steps need your accounts, so it should stop and ask you to do them. ## Unattended and CI use After the first login, create a deploy token and the agent or CI can deploy without a browser: ```bash pywa cloud deploy-tokens create agent --expires-in-days 30 export PYWA_CLOUD_TOKEN= export PYWA_CLOUD_BOT_ID= pywa deploy ``` See [Deploy tokens](/reference/cli/#deploy-tokens-ci) for scope and expiry. ## Tell your agent about it Add this to your project's `AGENTS.md` or `CLAUDE.md` so every session knows how to ship the bot: ```markdown ## Deploying This is a pywa WhatsApp bot hosted on Pywa Cloud (docs: https://docs.pywa.cloud/llms.txt). - Deploy: `pywa deploy` from the project root. Logs: `pywa cloud logs`. Status: `pywa cloud status`. - Secrets: `pywa cloud env set KEY --secret`. Never commit WhatsApp tokens. - Connecting or reconnecting a number (`pywa cloud connect`) and logging in need the user; ask them. ``` ## Machine-readable docs Every page here is also available as plain markdown (append `.md` to the URL), the whole site is at [`/llms.txt`](https://docs.pywa.cloud/llms.txt) (index) and [`/llms-full.txt`](https://docs.pywa.cloud/llms-full.txt) (everything in one file). # Connecting a WhatsApp Number Source: https://docs.pywa.cloud/guides/connecting-whatsapp.md Pywa Cloud is a Meta [Tech Provider](https://developers.facebook.com/documentation/business-messaging/whatsapp/solution-providers/get-started-for-tech-providers) — you don't create your own Meta App or manage your own system-user tokens. Instead, you connect a WhatsApp Business Account (WABA) to your **team** through Meta's **Embedded Signup** flow, hosted by Pywa Cloud, and then assign one of its phone numbers to a bot. When it finishes, Pywa Cloud injects everything your bot needs as regular [environment variables](/guides/environment-variables) — your code never has to know how the connection was made. A WABA connection belongs to your whole team, not a single bot — you only ever run Meta's popup once per WABA. A WABA can have several phone numbers; each one can be assigned to a different bot on the team, and reassigning a number from one bot to another later doesn't require repeating Meta's flow. ## Before you start Embedded Signup is Meta's flow, not Pywa Cloud's - have these ready before running `connect`: - **A Meta Business account** you can log into (personal Facebook credentials, used only to authenticate the flow - Meta does not share these with Pywa Cloud). - **A Business Portfolio** - select an existing one or create a new one as part of the flow. - **A WhatsApp Business Account (WABA)** - same: select an existing one or create a new one. - **A phone number.** A number that's never been used on WhatsApp before is verified by SMS/voice call as part of the flow. A number already active in the regular **WhatsApp Business App** can be connected too, side by side with the app (Coexistence) — no separate step, Meta's flow detects it automatically. - A few minutes to click through Meta's own Terms of Service screens along the way. None of this requires you to create your own Meta App - Pywa Cloud is a Meta [Tech Provider](https://developers.facebook.com/documentation/business-messaging/whatsapp/solution-providers/get-started-for-tech-providers) precisely so that individual tenants never need one. If your team already runs its own separate Meta App and system-user token, see [Bring your own Meta App](#bring-your-own-meta-app) instead. ## Connect a number ```bash pywa cloud connect ``` This is interactive. If your team has no WABA connected yet, it opens a one-time Meta Embedded Signup link in your browser: ``` To connect a WhatsApp Business Account, open: https://dashboard.pywa.cloud/connect// This link expires at 2026-09-03T12:15:00Z and can only be used once. Waiting for the connection to complete in your browser... ``` Click **Continue with Meta** and follow Meta's flow: log in with your Meta Business credentials, accept the ToS screens, select or create a Business Portfolio and a WABA, and verify a phone number. `pywa cloud connect` picks the new connection up automatically once you're done. If your team already has one or more WABAs connected, `connect` asks which one to use instead of opening Meta's popup again: ``` Which WABA connection do you want to use? 1) 987654321 (embedded_signup, active) 2) Connect a new WABA > 1 ``` Either way, the last step is picking which of that WABA's phone numbers this bot should use: ``` Which phone number should this bot use? 1) +1 555 0100 (Support) 2) +1 555 0101 (Sales) - currently used by 'sales-bot' > 1 ✅ Assigned phone '+1 555 0100' to this bot. ``` Assigning a number that's not registered with the Cloud API yet (freshly picked from a WABA that was only ever used elsewhere) registers it automatically. Picking a number away from another one of your bots stops routing new webhooks to it and restarts it so it drops the old token promptly. A number can belong to only one bot, and a WhatsApp Business Account to only one Pywa Cloud team at a time: connecting an account another team already holds is refused (unless their access has stopped working, in which case it moves to you and their bots lose the number). Don't connect a WABA and then sit on it unassigned for too long: Meta requires phone registration within 14 days of completing Embedded Signup, and registration only actually happens once you assign a number to a bot (deliberately deferred until there's a bot to register it against). The dashboard warns once you're past the halfway point with still no phone assigned; past 14 days, assigning a number for the first time could start failing on Meta's side. Pywa Cloud then saves `PYWA_TOKEN`, `PYWA_PHONE_ID` and `PYWA_WABA_ID` for this bot (the token as a secret — never readable back). There's nothing else to configure: no app id, no app secret, no callback URL ever touches your bot's environment — Pywa Cloud points the number's webhooks at your bot for you, server-side, as soon as you assign it (and again after every deploy). If Meta refuses, the assignment still stands but the bot's page and `connect-status` say messages are not reaching it; the bot's Settings page in the dashboard can try again. Check the result at any time: ```bash pywa cloud connect-status # 🟢 connected (WABA: 987654321, phone: 123456789, since 2026-09-03T12:14:02Z) ``` If Meta reports a problem with the underlying WABA (disconnected, restricted, or banned — see [Connection status changes](#connection-status-changes) below), `connect-status` surfaces it: ```bash pywa cloud connect-status # 🟢 connected (WABA: 987654321, phone: 123456789, since 2026-09-03T12:14:02Z) # ⚠️ underlying WABA connection is restricted - ``` The dashboard's bot page shows the same information under **WhatsApp**, with the same connect, assign, and disconnect actions available to any team admin. ## Building a bot for someone else's WABA If you're building a bot on behalf of a client who holds the real Meta Business credentials - not you - they're the one who has to click through Embedded Signup, since it's their WABA. The dashboard's **WhatsApp** card has a **Get a shareable link** button for exactly this: it starts the same Embedded Signup flow `pywa cloud connect` does, but as a link valid for 7 days (instead of the normal 15 minutes) that needs no Pywa Cloud login to open - copy it, send it to your client, and they complete the connection themselves. The page they land on names your team before anything else, so what they're authorizing is clear. No separate mechanism to learn - once they're done, it shows up exactly like any other connection, ready to assign a phone number to a bot. ## Using the connection in your code Read the values Pywa Cloud injected, exactly like every other pywa example: ```python import os from pywa import WhatsApp wa = WhatsApp( phone_id=os.environ["PYWA_PHONE_ID"], token=os.environ["PYWA_TOKEN"], ) ``` Don't pass `callback_url`/`callback_url_scope` - leave them unset. Pywa Cloud points your number's webhooks at your bot for you server-side, so `pywa` never needs to self-register a callback. (If you separately need `pywa`'s template-media or profile-picture upload helpers, which take an `app_id`, supply your own explicitly per call - Pywa Cloud's own Tech Provider app id isn't provided for that, since it's shared across every hosted bot.) ## Bring your own Meta App If your team already runs its own separate Meta App and system-user token, outside Pywa Cloud's Tech Provider relationship, connect it directly from the dashboard (the bot's Overview page) instead of running Embedded Signup, with the WABA id, a system-user token and your app secret. This validates the token by listing the WABA's phone numbers before saving anything - a bad token fails immediately. `--app-secret` (your Meta app's secret) is required: Pywa Cloud uses it to validate every inbound webhook signature for bots using this connection, same as the platform-owned path. Without it anyone who learned a webhook URL could forge messages to your bot, so a connection without it is refused. Once connected, assigning a phone number to a bot (`pywa cloud connect` or the dashboard) works identically to an Embedded Signup-sourced connection - `pywa`/Meta don't care which Meta App issued the token, only that it has the right permissions on that WABA/phone. Pywa Cloud subscribes its own app to the account when you connect it through Embedded Signup, and unsubscribes it when you disconnect the account. For a connection of your own Meta app, it never subscribes or unsubscribes anything of yours at connect or disconnect: your app's subscription is yours (it may serve your own server too). Pywa Cloud only sets the *number's* webhook override when you assign it, and removes that override when you unassign the number, delete the bot or disconnect the account. If removing the override fails (typically because the token has expired by then), it stays pointed at Pywa Cloud, which acknowledges and discards what arrives, and **your own server would receive nothing from that number** until it is cleared. The dashboard's WhatsApp page says so, and reconnecting the account with a working token (or **Try again** there) clears it. Otherwise clear it in your Meta app, or with: ```bash curl -X POST "https://graph.facebook.com/v26.0/" \ -H "Authorization: Bearer " -H "Content-Type: application/json" \ -d '{"webhook_configuration": {"override_callback_uri": ""}}' ``` Messages sent to a bot that was stopped on purpose, or suspended, are not queued: Pywa Cloud acknowledges and drops them, rather than have Meta hold them for 7 days and replay them all when the bot starts. A bot that is merely down (crashed, or mid-deploy) is retried by Meta. ## Coexistence with the WhatsApp Business App Connecting a number already active in the regular WhatsApp Business App (rather than a Cloud-API-only number) works the same way as above - Meta's Embedded Signup detects it and Pywa Cloud registers it idempotently, no separate step. Two things are specifically **your bot's own concern, not Pywa Cloud's**, once connected: - **Message/contact history sync** - the Graph API calls that pull existing history onto the Cloud API side (`history`, `smb_app_state_sync`) are made with your bot's own `PYWA_TOKEN`, from your own code, on your own schedule. Pywa Cloud doesn't initiate, wrap, or track these, including Meta's 24-hour sync-completion window - trigger them yourself if you need that history. - **`smb_message_echoes`** (messages sent from the phone itself, mirrored to the Cloud API) is already handled by `pywa` server-side once your webhook is registered - nothing extra to do. ## Connection status changes Pywa Cloud listens for Meta's own `account_update` webhook — the proactive signal that a WABA was disconnected from Pywa Cloud's Tech Provider app, deleted, restricted, or banned. This is the primary way a revoked or suspended connection is detected: a revoked token doesn't crash your bot, it just makes sends start failing, which is otherwise invisible to the platform. When this happens, every bot assigned a phone number from the affected connection shows the new status in `connect-status`/the dashboard, with Meta's own remediation message where one is given. Reconnecting (Embedded Signup or `waba connect-manual` again for the same WABA) clears it. ## Reconnecting or moving to a different number Running `pywa cloud connect` again for the same WABA refreshes its *stored* token in place - every bot assigned one of its phone numbers resolves the fresh token from then on, with no separate re-push step and no risk of a stale copy drifting out of sync in storage. To move a bot to a different phone number (same WABA or a different one), run `pywa cloud connect` again and pick a different number, or use `whatsapp assign` directly. **That's not the same as an already-*running* bot picking it up, though.** Your bot reads its environment once, when it starts - a running bot doesn't re-read it, and neither [`restart` nor `stop`/`start`](/guides/lifecycle/) change that either. It keeps working with the old token until a real redeploy happens. Same story for a plain env var you change with `env set`: the new value applies on the next real deploy, not instantly. Either kind of change flags the bot with pending changes - visible as a "Config changed" banner on the dashboard's Overview tab, with a one-click **Redeploy** action that applies your bot's current config fresh, no new code upload needed, to pick the change up. The CLI equivalent is `pywa cloud deployments rollback ` (find it with `pywa cloud deployments list --bot `) - same underlying action the dashboard's button calls, just without a dedicated shortcut command yet. # Database Integrations Source: https://docs.pywa.cloud/guides/database-integrations.md Pywa Cloud doesn't host a database for you — an order-tracking bot, a conversation log, or anything else your bot needs to persist brings its own database, the same as any other secret (see [Environment Variables & Secrets](/guides/environment-variables/)). What Pywa Cloud *does* do is make linking an existing database less annoying: connect your provider account once, pick the database for each bot, and its connection string is saved into the bot for you. Two providers are supported today: [Neon](https://neon.tech) and [Supabase](https://supabase.com) (both serverless Postgres). Pywa Cloud only asks for **read access** to your account and never creates, changes or deletes anything there. Redis Cloud and Logfire are not offered yet. ## Connect your account (once per team) A team admin or owner opens the team page in the dashboard, finds **Integrations** and clicks **Connect** next to the provider. You approve read-only access on the provider's own consent screen and land back in the dashboard. ## Link a database to a bot Open the bot's **Integrations** tab and click **Link a database**: - **Supabase:** pick the project, then type the project's database password. Supabase never shares it with anyone, so it has to come from you; if you've forgotten it, reset it in the project's database settings. - **Neon:** pick the organization (if you have several), the project, the branch and the database. No password to type. You can change the environment variable name (default `DATABASE_URL`), for example to `SUPABASE_DATABASE_URL` if `DATABASE_URL` is already taken. Pywa Cloud won't overwrite a variable that already exists on the bot. The connection string is saved as an encrypted secret and is never shown again; the tab only shows the variable's name. Check what's linked at any time in the bot's Integrations tab. ## Using it in your code ```python import os import psycopg # or your driver of choice conn = psycopg.connect(os.environ["DATABASE_URL"]) ``` Nothing Pywa-specific here — `DATABASE_URL` is a plain env var like any other secret this platform injects, in the standard `postgres://user:password@host/dbname` shape. ## What this doesn't do Linking a database doesn't trigger a redeploy on its own — your running bot doesn't see the new variable until your next real `pywa deploy`. This is deliberate: an unprompted redeploy is a real side effect (a brief downtime window, per [Deploying a Pywa Bot](/guides/deploying/)'s redeploy strategy). **Unlinking** a database (bot's Integrations tab) deletes its variable from that bot. **Disconnecting** a provider (team page) removes the team's access and every link made through it, but the variables already written stay on the bots, since they don't depend on the connection. This also isn't a managed-database product — Pywa Cloud never sees your database's actual data, only the connection string, and has no involvement in backups, scaling, or billing for it beyond what you already have with the provider directly. # Deploying a Pywa Bot Source: https://docs.pywa.cloud/guides/deploying.md `pywa deploy` takes an ordinary pywa project and turns it into a running, always-on bot — no build config, nothing to write beyond the pywa code you'd write anyway. ## What your project needs - **A dependency file that declares `pywa[server]`**, pinned to a version. Any of `uv.lock`, `pylock.toml`, `pyproject.toml`, or `requirements.txt` work — whichever your project already uses. Pywa Cloud doesn't pin a pywa version for you; that choice stays entirely yours, like any other dependency. - **A discoverable `WhatsApp` instance** — found the exact same way `pywa run` finds one locally: a conventionally named file (`main.py`, `app.py`, `wa.py`, or `bot.py`, at the project root or under `app/`, `bot/`, `wa/`, or `src/`) with a module-level variable named `wa`, `bot`, `client`, `app`, or `main`. That's the whole contract — if `pywa run` already works on your machine, `pywa deploy` will work too. If your project doesn't fit that convention — a different filename, a differently-named variable — point at it explicitly instead of restructuring your project: ```bash pywa cloud bots create my-bot --entrypoint-override my_module:my_whatsapp_instance # or on an existing bot: pywa cloud bots set-entrypoint my_module:my_whatsapp_instance # back to automatic discovery: pywa cloud bots set-entrypoint ``` ### Python version Pywa Cloud currently supports **3.10 through 3.14**. Which one your bot actually runs on is controlled by your project, never assumed by the platform: 1. `requires-python` in `pyproject.toml` — if your project already declares one (e.g. `">=3.11"`, just an example, not a minimum Pywa Cloud imposes), the newest supported version satisfying it is used. 2. A `.python-version` file (the `pyenv`/`uv` convention) — used directly if supported. 3. Neither present → the newest version Pywa Cloud supports. A pin that no supported version satisfies (e.g. `">=3.16"`, ahead of what's supported, or `"<3.10"`, behind it) fails the build with a clear message listing the supported versions, rather than silently falling back to something else. ## Deploying From your project's directory: ```bash pywa deploy ``` A directory's first deploy asks which bot this is — pick an existing one or create a new one on the spot — and remembers the answer, so every deploy after that is just `pywa deploy` again, from anywhere in the project. To skip the prompt (useful in scripts), pass `--bot` directly: ```bash pywa deploy --bot my-bot ``` A successful deploy prints something like: ``` 📦 Packaging /path/to/my-bot... 🚀 Deploying (1842 bytes)... ✅ Deployed (python 3.13-slim) ``` If something goes wrong, `pywa deploy` prints where it stopped and why, and exits non-zero — see [Troubleshooting](/guides/troubleshooting/) for the most common failure messages and what they mean. Prefer a UI? The dashboard's **Deployments** tab on a bot's page does the same thing via a drag-and-drop upload, with the same deploy log and history — everything in this guide works either way, CLI or dashboard. ## What actually happens Every deploy replaces the previous running version outright — it never runs the old and new version side by side. This is deliberate, not a limitation: a pywa bot keeps some state in memory (pending `wa.listen()` calls, its duplicate-webhook cache), and two copies of the same bot processing the same WhatsApp number at once would risk a webhook handled twice, or a reply landing on the wrong process. In practice this means a redeploy has a brief moment of real downtime — long enough to swap the old process for the new one, not longer. Every successful deploy is kept, so you can go back to one if a new version turns out to be broken — see [`deployments rollback`](/reference/cli/#deploying) in the CLI reference. ## Working in a monorepo If your bot lives in a subdirectory alongside other things (a monorepo with several services), point the bot at that subdirectory instead of restructuring the repo: ```bash pywa cloud bots create my-bot --bot-directory bots/backend # or on an existing bot: pywa cloud bots set-directory bots/backend # back to deploying from the project root: pywa cloud bots set-directory ``` The subdirectory needs its own dependency file and its own discoverable `WhatsApp` instance (or entrypoint override), exactly as if it were the whole project. Everything else you deploy alongside it is uploaded but ignored. ## What gets left out of a deploy Two layers, so you never have to think about what "shouldn't" be uploaded: - **Always excluded**: `.venv`, `.git`, `__pycache__`, `.pywacloud`, and anything starting with `.env`. Not configurable, on purpose — nobody wants their git history or a virtualenv shipped by accident. - **`.gitignore`**, respected by default — anything git already wouldn't track, a deploy won't upload either. - **`.pywacloudignore`** — same syntax as `.gitignore` (one pattern per line, `!` to un-ignore), evaluated *after* `.gitignore`, so it can override it in either direction: exclude something git tracks but a deploy doesn't need (`tests/`, `docs/`), or include something git ignores but a deploy does (a built frontend bundle in `dist/`, say): ``` # .pywacloudignore tests/ !dist/ ``` ## Linking a directory to a bot A directory's first deploy writes a small `.pywacloud/link.json` file (git-ignored automatically) so future deploys know which bot to target without asking. You can also set or change the link explicitly: ```bash pywa cloud link [path] pywa cloud unlink [path] ``` ## Deploying from CI A linked directory or `--bot` both work fine from CI, but they still act as *you* — for a credential scoped to exactly one bot and nothing else, use a [deploy token](/reference/cli/#deploy-tokens-ci) instead: ```bash export PYWA_CLOUD_TOKEN= export PYWA_CLOUD_BOT_ID= pywa deploy ``` `pywa cloud setup-ci` scaffolds a ready-to-use GitHub Actions workflow around exactly this — see [CI setup](/reference/cli/#ci-setup). # Environment Variables & Secrets Source: https://docs.pywa.cloud/guides/environment-variables.md pywa itself never reads environment variables for you — your project's own code reads them via `os.environ` and passes them to `WhatsApp(...)`, exactly like every pywa example does: ```python import os from pywa import WhatsApp wa = WhatsApp( phone_id=os.environ.get("PYWA_PHONE_ID"), token=os.environ.get("PYWA_TOKEN"), ) ``` Pywa Cloud's job is getting the values you set into your bot's environment at deploy time — nothing more magical than that. :::note[`PYWA_TOKEN`, `PYWA_PHONE_ID`, and friends aren't yours to set] `PYWA_TOKEN`, `PYWA_PHONE_ID` and `PYWA_WABA_ID` are reserved — the platform injects them for you once you [connect a WhatsApp number](/guides/connecting-whatsapp/), and `env set` rejects any attempt to set one of these keys yourself, by design. This page is for your *own* config and secrets — an LLM API key, a database URL you're not using the [built-in integrations](/guides/database-integrations/) for, a feature flag, anything your bot needs that Pywa Cloud has no opinion about. ::: ## Setting a variable ```bash pywa cloud env set OPENAI_API_KEY "sk-..." --secret pywa cloud env set LOG_LEVEL DEBUG ``` `env set` is create-or-update: if the key doesn't exist yet, it's created with whatever `--secret` flag you passed; if it already exists, only its *value* is updated. ## When it actually takes effect Not instantly. Your bot picks up its environment once, when it starts — a running bot doesn't re-read it, and [`restart`](/guides/lifecycle/) doesn't change that either, so `env set`/`env delete` change what the *next real deploy* will apply, not what's running right now. Your bot is flagged as having pending changes the moment you change one — shown as a "Config changed" banner on the dashboard's Overview tab — until you `pywa deploy`, or use the dashboard's one-click **Redeploy** (applies your bot's current config fresh, no new code needed). ## Plain vs. secret The `--secret` designation is fixed the moment a key is first created, and can never change afterward — not by omitting `--secret` on a later `env set`, not any other way. If you try, the CLI updates the value but tells you the flag was ignored: ``` ✅ Updated 'OPENAI_API_KEY' on my-bot (--secret ignored: the secret/plain designation is fixed at creation) ``` A **secret** value is never returned by any command or API call once set — not in `env get`, not in `env list`, not right after the `env set` that created it. If you lose it, there's no way to retrieve it: delete the key and set it again. A **plain** value is always readable back — useful for non-sensitive config like `LOG_LEVEL`, where seeing the current value is more useful than hiding it. ```bash pywa cloud env list pywa cloud env get OPENAI_API_KEY # → OPENAI_API_KEY= (updated ...) pywa cloud env get LOG_LEVEL # → LOG_LEVEL=DEBUG pywa cloud env delete LOG_LEVEL ``` The dashboard's **Environment** tab does the same create/update/delete, with one extra convenience the CLI doesn't have: an optional "redeploy now" checkbox, so a config change can go live without a separate `pywa deploy`. ## Encryption at rest Secret values are encrypted at rest, and only ever decrypted at the moment they're injected into your bot's running environment — never in transit as plain text, never sitting in storage unencrypted, and never returned by the API or dashboard again once saved. See [Security & Isolation](/guides/security/) for the full picture of what is and isn't guaranteed around your bot's data. # Hosting a WhatsApp Bot Source: https://docs.pywa.cloud/guides/hosting-a-whatsapp-bot.md A WhatsApp Cloud API bot is a web server that Meta calls. That sets what any host has to provide. ## What the host must provide 1. **A public HTTPS URL** that Meta can reach. `localhost` and plain HTTP do not work, so a bot on your laptop needs a tunnel (see [Local Development](/guides/local-development/)) or a deployed server. 2. **Webhook verification.** When you register the URL, Meta sends a `GET` with a verify token and expects the challenge echoed back. pywa answers this for you once the URL reaches your bot; the usual cause of "verification failed" is that the URL does not reach the bot, or the token differs. 3. **Signature checking.** Meta signs every webhook `POST` with your app secret. pywa verifies it; do not disable it. 4. **An always-on process.** Messages arrive when users send them. Hosts that sleep or scale to zero can miss or delay webhooks and lose the conversation state held in memory. 5. **Secrets.** The access token, phone number ID and app secret belong in environment variables, not in code. ## Your options Any host that gives you an always-on process and a public HTTPS URL can run a pywa bot: a VPS behind a reverse proxy, or a general platform such as Render, Railway or Fly.io. You then configure the webhook URL and verify token in the Meta app yourself and manage restarts, logs and TLS. **Pywa Cloud** is built for this one job. `pywa deploy` uploads the project, builds it and runs it in its own container with a stable public webhook URL; the Meta verification handshake and phone number connection are handled for you (`pywa cloud connect`), and `pywa cloud logs`, `status`, `restart` and rollback are built in. Each bot runs isolated from other customers' bots. ## Getting started ```bash pip install pywa-cloud-cli pywa login pywa deploy pywa cloud connect ``` Full walkthrough: [Quick Start](/getting-started/quick-start/). Using a coding agent: [Deploying with an AI Agent](/guides/ai-agents/). Webhook problems: [Troubleshooting](/guides/troubleshooting/). # Managing a Running Bot Source: https://docs.pywa.cloud/guides/lifecycle.md ```bash pywa cloud status [--bot ] pywa cloud stop [--bot ] pywa cloud start [--bot ] pywa cloud restart [--bot ] ``` All four default to the linked bot if `--bot` is omitted, same as [`logs`](/guides/logs/). None of them rebuild anything — for that, see [Deploying a Pywa Bot](/guides/deploying/). The dashboard's **Overview** tab shows the same live status/health and has the same Stop/Start/Restart buttons, for anyone who'd rather not reach for a terminal. ## What actually happens - **`status`** is queried live, every time you run it — nothing is cached or tracked separately. Shows whether your bot is running, its current state (running, exited, restarting, ...), how many times it's restarted since it was deployed, and when it last started. - **`stop`** stops your bot without discarding it, so `start` can resume it later with no rebuild. - **`start`** resumes a stopped bot. - **`restart`** stops and starts it in place. This does **not** pick up environment variable changes made since the last deploy — those need [`deploy`](/guides/deploying/) again, since `restart` reuses exactly what was already built and running, with whatever was injected at that time. ## Crash recovery — what's automatic, and what isn't Every deploy runs your bot with an automatic-restart policy. In practice: - If your bot's own process crashes or exits unexpectedly, **it's restarted automatically** — nothing here needs to notice or act. - If you `pywa cloud stop` it deliberately, that's respected and it stays stopped — it won't fight you by restarting on its own. Only `start` (or a fresh `deploy`) brings it back. - If the platform itself restarts for any reason, the same policy brings your bot back up automatically once it's running again. What's genuinely **not** covered yet: nobody is watching whether a *running* bot is actually serving traffic correctly — "the process is alive" (which `status` shows you) and "the process is working correctly" aren't the same thing, and only the first is currently visible. If your bot is running but silently broken (bad credentials, an unhandled exception in a specific handler, etc.), `status` will still say `running`. Check [Logs](/guides/logs/) if something seems off despite a healthy-looking status, or look at the line `pywa cloud status` prints about whether your bot is actually answering requests, not just alive. # Local Development Source: https://docs.pywa.cloud/guides/local-development.md Only a bot in `development` can be tunnelled (new bots start there); promoting a bot to production (in the dashboard) moves it out of development, where the tunnel is refused. See [CLI reference](/reference/cli/#environments). Normally, developing against real WhatsApp webhooks means running a separate tunnel tool (ngrok or similar) and manually repointing the callback URL in the Meta App dashboard for every session - then pointing it back at your deployed bot afterward. Pywa Cloud's tunnel does this without either step: your bot already has one stable public webhook URL (`https://ingress.pywa.cloud/webhook/` - your bot's opaque id - registered once when you [connect a WhatsApp number](/guides/connecting-whatsapp/)) - the tunnel just changes where Pywa Cloud forwards traffic arriving at that URL, from your deployed bot to your own machine. The URL registered with Meta never has to change between local development and production. `pywa dev --tunnel` goes one step further than a plain relay, too: it fetches this bot's real, live `PYWA_TOKEN`/`PYWA_PHONE_ID`/`PYWA_WABA_ID` and injects them into your local process's environment before starting - the same values your deployed bot has, not a foreign override. It also injects every variable and secret set with `pywa cloud env`, except where your shell or `.env` already sets one - your local value wins there, so you can point `DATABASE_URL` at a local database. (Needs the admin role on the bot's team, like the tunnel itself.) Because this sends live customer messages to your machine and runs your code with the bot's real token, `pywa dev --tunnel` says so and asks for a yes first (a script with no terminal is told and goes ahead). Opening a tunnel and fetching the environment are both recorded in the team's audit log, and a tunnel ends within about 30 seconds of its token being revoked or your admin role being removed. Without them your local bot would receive real webhooks but be unable to send replies at all, so there's no real use case for tunneling without them. (If your bot has no WhatsApp number connected yet, this fails fast with a clear error - connect one first.) This is unconditional, not opt-in - anything your project's own `.env` or hardcoded values set for the three WhatsApp names is overwritten by the real ones. The standalone `pywa cloud tunnel` below is different: it's a byte- level relay with no server of its own to inject into, so it doesn't do this - your local process keeps running against whatever credentials it already had. ## Usage The recommended way is `pywa dev --tunnel` (pywa's own local dev server, with the tunnel and credential injection wired in), from the linked project directory (or with `--bot `): ```bash pywa dev --tunnel # runs your bot locally, injects its real WhatsApp credentials, and relays # this bot's webhook traffic here ``` ``` Injected live WhatsApp credentials: PYWA_PHONE_ID, PYWA_TOKEN, PYWA_WABA_ID. Injected env vars from Pywa Cloud: OPENAI_KEY. 🚀 Starting Pywa in development mode 🌐 Server URL: http://127.0.0.1:8000 Tunneling 'my-bot''s webhook traffic to http://127.0.0.1:8000 ... ``` `--tunnel` picks up `--host`/`--port`/`--bot` the same way the rest of `pywa dev` does - `--bot ` if the directory isn't linked to one already. ### Standalone tunnel — relay only, no credential injection If you're not using `pywa dev` - a different framework runner, or you'd rather run your bot and the tunnel as two separate steps - run your bot locally first, exactly as you would with any other Python HTTP server, providing its `PYWA_TOKEN`/`PYWA_PHONE_ID`/etc. yourself however you normally would for a local run (a `.env` file, hardcoded values, `pywa cloud env list` copied by hand - `pywa cloud tunnel` itself won't fetch these for you, unlike `pywa dev --tunnel` above): ```bash python main.py # or however you normally run it - note the port it's listening on ``` Then, from the linked project directory (or with `--bot `): ```bash pywa cloud tunnel --port 8000 # the port your bot above is listening on ``` ``` Tunneling 'my-bot''s webhook traffic to http://127.0.0.1:8000 ... Press Ctrl+C to stop and hand control back to the deployed container. Connected - forwarding webhook traffic to http://127.0.0.1:8000 POST /webhook -> 200 ``` ## What happens either way From this point, every webhook Meta sends for this bot arrives at your local process instead of the deployed one - signature-validated exactly the same way it would be in production (validation happens once, before Pywa Cloud decides where to send the request - what changes is only *where* an already-validated request goes). **Ctrl+C** (or closing your laptop, losing WiFi, anything that drops the connection) immediately hands control back to your deployed bot - nothing about your bot's deployment or its Meta configuration needs to change either way, and your deployed bot is never stopped while a tunnel is connected, only temporarily not receiving traffic. ## A few things worth knowing - **Opt-in, not automatic.** The tunnel is only active while `pywa dev --tunnel`/`pywa cloud tunnel` is actually running - starting your bot locally on its own (plain `pywa dev`, or `python main.py`) doesn't reroute anything. - **One tunnel per bot at a time.** Starting another tunnel for the same bot (e.g. a teammate starts one while yours is still connected) takes over - your own connection is closed with a clear reason, not silently starved of traffic with no explanation. - **Visible from the dashboard too.** The Overview tab shows a "Local tunnel active" badge with how long it's been connected, whenever one is - useful for a teammate wondering why the deployed version isn't seeing traffic it should be, without needing terminal access to whoever's tunneling. - **No request buffering across a reconnect.** A dropped connection doesn't queue up in-flight webhook deliveries to replay once you're back - Meta already retries failed webhook deliveries, which is a simpler and more robust safety net than building that here. - **This is a webhook relay, not a general tunnel.** It doesn't expose anything beyond the webhook path, and doesn't replace `pywa cloud logs` or any other existing command. # Logs Source: https://docs.pywa.cloud/guides/logs.md ```bash pywa cloud logs --bot pywa cloud logs --bot --tail 500 pywa cloud logs --bot --follow ``` If you're in a directory linked to a bot (see [Linking a directory to a bot](/guides/deploying/#linking-a-directory-to-a-bot)), `--bot` isn't needed — it uses the linked bot. This shows your running bot's console output: pywa's own startup banner, anything your handlers log via the standard `logging` module, and any errors pywa itself logs (a failed handler, a malformed update, and so on). ## What this is, and isn't Without `--follow`, each call is a **point-in-time snapshot** — the last `--tail` lines at the moment you ran the command, defaulting to 200. `--follow` keeps going until you press Ctrl+C, printing new lines as they show up — but it's **polling underneath**, not a persistent live-tail connection: every `--interval` seconds (default 2), the CLI checks in for anything logged since its last check. This is usually not something you'll notice, but it does mean genuinely instant updates aren't guaranteed (you may see a line up to `--interval` seconds after it was actually logged), and there's no persistent log storage beyond what's still available from your bot's current run — neither `logs` nor `logs --follow` remembers anything from before your bot last started. If the bot has never been deployed, or isn't currently running, `logs` returns a clear error rather than an empty response — there's a real difference between "nothing has been logged yet" (empty output, totally normal for a freshly deployed bot) and "there's nothing running to fetch logs from at all." The dashboard's **Logs** tab shows the same output, polling the same way `--follow` does — useful when you want to glance at a bot's logs without a terminal open. # Security & Isolation Source: https://docs.pywa.cloud/guides/security.md Every bot runs in its own isolated, sandboxed environment on shared hardware. This page describes exactly what that does and doesn't protect against, so you can decide whether it's the right fit for what you're deploying — not as a marketing claim. :::danger[More hardening is still coming] Everything described below is real and active today, not aspirational — this page describes what the platform actually does, not a roadmap. It also isn't the finished security architecture: Pywa Cloud is pre-GA and under active development, and more hardening is planned on top of what's already here. See [Production limitations](#production-limitations) below for the specific gaps as of today, and ask before deploying anything genuinely sensitive. ::: ## What isolates your bot - **Its own private network**, with nothing else attached to it. Two bots genuinely cannot reach each other over the network, even by IP — verified directly, not just asserted. - **Runs as an unprivileged, restricted process** with no elevated system permissions and no way to acquire any — your code has nothing it would need root or a special capability for, and can't get one even if it tried. - **A read-only filesystem**, with a small, size-capped scratch space for incidental writes (a media attachment downloaded from the WhatsApp API before you process it, say). Nothing your code writes there survives a redeploy or restart, and nothing it writes can fill up shared storage. - **CPU, memory, and process limits**, applied identically to every bot — one runaway or malicious process can't starve the platform or other tenants of resources. - **No access to the underlying host** — not its filesystem, not its other processes, not the systems that manage the platform itself. Your code cannot see or affect anything outside its own sandbox, at build time or at run time. - **A build timeout and an upload size limit** — a build that hangs or an oversized upload fails cleanly instead of consuming resources indefinitely. ## What this deliberately does not claim - **This is process-level isolation, not VM isolation.** Every tenant shares the same underlying kernel on the same host. This is a real, meaningful boundary — not the same guarantee a hypervisor-level VM boundary provides. If your threat model specifically requires VM-level isolation, the current architecture doesn't provide it. - **Outbound traffic shares an IP.** Every bot on a given host currently sends outbound requests (including to Meta's Graph API) from that host's one public IP — there's no dedicated per-bot egress IP yet. - **Not yet a multi-region or highly-available deployment.** See [Production limitations](#production-limitations) below. ## Reporting abuse Every bot's outbound traffic currently leaves through one shared IP (see above) — if you believe a bot hosted on Pywa Cloud is sending spam, scraping, attacking a service, or otherwise behaving abusively, email **abuse@pywa.cloud** with what you're seeing (source IP/timestamps if you have them, and what the traffic looked like). Reports are the primary way a specific bad actor gets found and stopped without penalizing every other tenant sharing that IP. ## Production limitations This is an early-stage platform. Being direct about what that means in practice: - **No independent, third-party security audit or penetration test has been performed.** An internal adversarial review has (real findings, fixed - hardcoded fallback secrets that would have silently run in production if misconfigured, a signature-validation fail-open path, a missing role check on one endpoint, an unbounded-upload memory exhaustion path, among others) - a genuine pass, not a formality, but still the team building the platform reviewing its own work, not an outside assessment. - **Browser sessions are an `httpOnly` cookie, with CSRF protection.** The session cookie is scoped to the API host only, is invisible to JavaScript (so an XSS bug can't read or exfiltrate it), and is `Secure` + `SameSite=Lax`. Any write made with it must also come from an allow-listed origin and carry a custom header, since `SameSite` alone doesn't stop a sibling subdomain. The optional Pywa Studio sign-in uses the same cookie but is least-privileged: from Studio's origin it can only read who is signed in and use Studio-specific endpoints, never change the account, manage teams, touch secrets or deploy tokens. Sessions slide: they expire after 7 days without use (renewed whenever you're active) and can never outlive 30 days from the original sign-in. "Log out everywhere" invalidates every one of them. The one exception is the operator admin panel, which still keeps its single shared admin token in `localStorage` - a known gap, tied to the shared-credential item below. - **The platform's own backend has broader host access than any tenant's sandbox does**, by necessity of managing it. Further separating that from the tenant-isolation boundary described above is ongoing hardening work, not yet finished - the isolation guarantees above don't depend on it, but ask if the distinction matters for your threat model. - **Admin operations currently use a single shared operator credential**, not per-person accounts. Fine for a single operator; if you're evaluating this as an organization with multiple support/ops staff, ask about per-admin audit trails before relying on them. - **No independent per-tenant network egress control or outbound-abuse-detection system** exists yet beyond basic per-tenant rate limiting on inbound traffic. - **Backups exist and have been tested**, but a specific production deployment's own backup/restore procedure should be verified against that deployment's real data before being relied on. If any of the above is a blocker for your use case, ask before deploying anything sensitive — this page will be updated as the architecture changes, not left to go stale while the platform evolves. # Troubleshooting Source: https://docs.pywa.cloud/guides/troubleshooting.md ## Login / setup **`Not logged in. Run pywa cloud login first.`** — every command except `login` needs a stored token. Run `pywa login`. **`Could not reach the control plane at `** — the CLI couldn't connect at all (a network/ firewall issue) — distinct from an authentication failure, which would connect fine and return a 401/403 instead. **`Invalid email or password`** (signup/login) — exactly that; there's no separate "account doesn't exist" vs. "wrong password" message, deliberately, so a failed login attempt can't be used to enumerate which emails have accounts. **`Verify your email address before creating or deploying bots.`** (403 from `bots create` or `deploy`) — signing up sends a verification email, and both actions are blocked until you click the link in it. Check your inbox (and spam folder) for the email from signup; there's no CLI resend command yet, but the dashboard's "check your email" screen has a resend action. ## Deploy failures `pywa deploy` says where the deploy stopped (preparing, building, checking, starting) and why, with the failing step's own output — usually the pip/uv error or your bot's traceback. The step-by-step deploy log is `pywa cloud deployments log `. A few failure modes worth knowing about specifically: - **`Python syntax check failed`** — every `.py` file in your project is checked before the build even starts, so a syntax error fails fast with a clear file/line rather than a slower, vaguer build failure. If you're on macOS and see a syntax error in a file you don't recognize (e.g. `._main.py`), that's not your code — see below. - **A file like `._main.py` shows up in the error** — macOS's `tar` command writes an invisible "AppleDouble" metadata file (`._`) alongside any file with extended attributes when you archive a project by hand. These are automatically ignored during the syntax check, so this shouldn't happen from a current CLI/dashboard version — if you see it, you're likely using an old version or building the archive with a different tool; update and retry. - **`Project must include one dependency file: uv.lock, pylock.toml, pyproject.toml, or requirements.txt`** — exactly that; add one of these declaring `pywa[server]` (not just `pywa` — the `[server]` extra is what pulls in the web server your bot actually runs on). If the file *is* present but doesn't declare the right extra, the build itself will still succeed, but your bot will fail to start instead (see "keeps restarting" below) — this check only catches the file being missing entirely. - **Archive too large** — the current limit is 50MB. Make sure `.venv`/`__pycache__`/`.git` aren't being included (excluded automatically by the CLI's own archive builder, but a hand-built archive via the dashboard's file-upload flow won't get that for free). - **Build timed out** — the default build timeout is 10 minutes. A build that legitimately needs longer than that (a very large dependency set) is unusual — check whether a dependency is hanging on a slow/unreachable index first. ## After a successful deploy, the bot keeps restarting Check `pywa cloud status` for `restart_count` and whether it's flagged as a likely restart loop, then `pywa cloud logs` for what's actually crashing. The most common first-deploy cause: the bot reads `PYWA_TOKEN`/`PYWA_PHONE_ID` and they aren't set yet. These aren't something you set by hand — they're reserved keys the platform injects only once you connect a real WhatsApp number (`pywa cloud connect`, or the dashboard's **WhatsApp** tab); `env set` will actively refuse them if you try. A crash-looping bot with no WhatsApp number connected yet is expected, not broken. If the log says `When listening for incoming updates, a `verify_token` must be provided`, you're on a pywa older than 4.5.0, which insists on one. Pywa Cloud answers Meta's verification handshake itself, so the value is never checked — pass any string (`verify_token="unused"`) or upgrade pywa. ## Health check says "unhealthy" — what do the reasons mean? Why an HTTP request at all, rather than just checking that your bot's process is still running? Because "the process exists" and "it's actually working" aren't the same thing — a process can be alive but hung or stuck without ever really starting to serve requests, and a simple liveness check won't catch that (see `status`'s own caveat in [Managing a Running Bot](/guides/lifecycle/#crash-recovery--whats-automatic-and-what-isnt)). An unauthenticated GET to your bot gets real proof of life instead — specifically a GET to `/__pywacloud_health__`, a reserved path nothing in your own app would ever handle (not your webhook, not a `@wa.on_flow_request(...)` path). Getting a plain 404 back is still real proof your bot started and is genuinely answering requests, not just that *some* process happens to be alive. This is deliberately **not** a request to your actual webhook. An earlier version of this check did exactly that, and it worked — but it meant every single health check logged a genuine `WARNING pywa.server: Failed verification challenge: invalid verify token` line into your own `pywa cloud logs`, indistinguishable at a glance from a real failed request. Hitting a path your own app never handles avoids that entirely — a health check now writes nothing to your logs. There's still no separate `/health` route, because pywa itself doesn't have one, and adding one would be a change to pywa made purely for this platform's convenience. `pywa cloud status` (and the dashboard) report one of these for a running bot: - **`ok`** — healthy: the app answered the reserved path with the 404 expected of a live server. - **`not_running`** — your bot isn't running at all; check `status` first. - **`no_port_mapping`** — your bot is running but not yet reachable for a health check (typically right after a deploy) — retry in a few seconds. - **`unreachable`** — your bot is running but didn't respond to the health check at all (still starting up, or genuinely stuck) — check `logs`. - **`unexpected_response`** — your bot responded, but not with the expected 404 — worth checking `logs` for what's actually being served. ## `429 Too Many Requests` Rate limits exist on a handful of specific actions - each keyed narrowly, so hitting one doesn't block anything else you're doing: - **Login** - 20/minute per IP, and separately 10/minute per email address (so one person hammering their own forgotten password can't lock a different account out by IP alone). - **Signup** - 10/minute per IP. - **Resend verification email** - 3/minute per account. - **Triggering a deploy** (including rollback) - 10/minute per bot, checked before any build work starts - this one is per-bot, not per-token or per-IP, since the concern is one bot's own deploy loop eating build resources, not credential abuse. All temporary and per-minute - wait a minute and retry. None of these apply to your bot's own *incoming* WhatsApp traffic, which has a separate, much higher limit (600/minute) sized for real message volume, not account actions. ## Still stuck? Include the full output of `pywa cloud status` and the last 50-100 lines of `pywa cloud logs` when asking for help — most of what's needed to diagnose a stuck deploy is in those three, not in describing the symptom alone. # WhatsApp Flows Source: https://docs.pywa.cloud/guides/whatsapp-flows.md A [WhatsApp Flow](https://developers.facebook.com/docs/whatsapp/flows) 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 Unlike your bot's regular webhook (registered for you automatically once [connected](/guides/connecting-whatsapp/)), 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](https://dashboard.pywa.cloud) → **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: ```python 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//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//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`](/guides/local-development/) - 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](/reference/cli/) for what does and doesn't have a command). ## 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`): ```python 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: ```python wa.set_business_public_key(public_key=open("public.pem").read()) ``` ## Two independent layers of authentication 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. # CLI Reference Source: https://docs.pywa.cloud/reference/cli.md `pip install pywa-cloud-cli` gives you every command below, reached as `pywa cloud ` — installing it pulls in `pywa` itself too, and `pywa`'s own CLI automatically mounts `pywa cloud ...` on top of it. A handful of the most common commands also get a top-level shortcut directly on `pywa`, shown below wherever one exists: `pywa login`, `pywa logout`, `pywa whoami`, `pywa deploy`. Run `pywa cloud --help` or `pywa cloud --help` (or, for a shortcut, `pywa --help`) for the exact same information this page describes, straight from the CLI itself. ## Auth ### `pywa login` ```bash pywa login # opens a device-code flow pywa login --token # CI / scripted login ``` (equivalent to `pywa cloud login`) With no `--token`, `login` starts a real device-code flow: it prints a short code and opens a confirmation page in your browser, where you sign in and approve it; the CLI polls until you do, or the code expires after 10 minutes. `--token ` skips all of that and logs in directly with an existing token — the CI path, and also how a [deploy token](#deploy-tokens-ci) is normally used. No account yet? Sign up at [dashboard.pywa.cloud](https://dashboard.pywa.cloud) — that's also where you'd be sent by the device-code link above if you're not already signed in. Either way, the resulting token is stored at an OS-standard config location — never in your project directory, so it can't end up committed by accident: - macOS: `~/Library/Application Support/pywa-cloud/auth.json` - Linux: `$XDG_CONFIG_HOME/pywa-cloud/auth.json` (default `~/.config/...`) - Windows: `%APPDATA%\pywa-cloud\auth.json` Once you've logged in, every other command in this reference just works. `$PYWA_CLOUD_CLI_CONFIG_DIR` overrides the config location entirely, useful for running more than one isolated login on one machine. ### `pywa logout` Forgets the stored login. (equivalent to `pywa cloud logout`) ### `pywa whoami` Shows the identity the current login resolves to, and which API it's pointed at. (equivalent to `pywa cloud whoami`) ## Bots Commands that act on one bot use the bot linked to the current project (`.pywacloud/link.json`, written by `pywa deploy` or `pywa cloud link`). Pass `--bot ` to target another one, or set `PYWA_CLOUD_BOT_ID`. ```bash pywa cloud bots create [--entrypoint-override ] [--bot-directory ] pywa cloud bots list pywa cloud bots get [] pywa cloud bots delete [] [--yes] pywa cloud bots set-entrypoint [] [--bot ] pywa cloud bots set-directory [] [--bot ] ``` `` is only a display name; a bot is identified by its id. Deleting a bot also stops it, if it's currently running. `set-entrypoint` sets or (called with no `module:var`) clears the bot's entrypoint override — see [Deploying a Pywa Bot](/guides/deploying/) for when you'd need one. `set-directory` sets or (called with no `path`) clears the bot's application directory, for deploying one member of a monorepo — see the same guide's "Working in a monorepo" section. ## Environment variables & secrets ```bash pywa cloud env set [] [--secret] [--bot ] pywa cloud env get [--bot ] pywa cloud env list [--bot ] pywa cloud env delete [--bot ] ``` See [Environment Variables & Secrets](/guides/environment-variables/) for the full semantics — `set` is create-or-update, and `--secret` is fixed at creation. ## Scaffolding a project There's no scaffolding command in `pywa-cloud-cli` itself — use pywa's own project generator, with `--cloud` so the result is deployable as-is: ```bash pywa new --cloud [--async] [-o ] ``` This writes `main.py` (credentials read from `PYWA_PHONE_ID`/`PYWA_TOKEN`, no hardcoded values, no local tunnel setup) plus a real `pyproject.toml` and `.gitignore` — ready for `pywa deploy` as-is. Plain `pywa new` (no `--cloud`) is pywa's own default scaffold instead: meant for editing and running locally, not deploying as-is. See `pywa new --help` (or [pywa's own docs](https://pywa.readthedocs.io)) for the full set of options. [Deploying a Pywa Bot](/guides/deploying/) covers what a project needs to be deployable if you'd rather write one from scratch or adapt an existing project. ## Linking a directory ```bash pywa cloud link [path] pywa cloud unlink [path] ``` `path` defaults to the current directory. See [Deploying a Pywa Bot](/guides/deploying/) for how this interacts with `deploy`. ## Deploying ```bash pywa deploy [path] [--bot ] ``` (equivalent to `pywa cloud deploy`) A directory's first deploy asks which bot this is (Enter picks the bot named like the directory, or creates a new one; pass `--bot` to skip the prompt — required in CI, where there's no terminal to ask); later deploys in the same directory reuse the link automatically. In a terminal, `deploy` also does what the deploy needs: if the bot has no WhatsApp number it runs the `connect` steps first (CI fails at once instead, before uploading), and it offers to set the variables from a local `.env` that the bot doesn't have yet. It refuses an upload over the 50 MB limit and lists the biggest files. See [Deploying a Pywa Bot](/guides/deploying/) for what actually happens and what's excluded from the upload. ```bash pywa cloud deployments list [--bot ] pywa cloud deployments get [--bot ] pywa cloud deployments log [--bot ] pywa cloud deployments rollback [--bot ] ``` `deployments list` shows past deployments for a bot (status, Python version, timestamp). `deployments get` fetches full metadata for a specific deployment attempt. `deployments rollback` re-runs a previous *successful* deployment's already-built version directly — no re-upload, no rebuild — using the bot's *current* env vars (so a secret rotated since then still applies), and records a new deployment rather than mutating the old one. Requires the Admin/Owner team role. `deployments log` (alias `logs`) shows that deployment's deploy log: one line per step, plus your bot's own output if it failed to start. ## Managing a running bot ```bash pywa cloud status [--bot ] pywa cloud stop [--bot ] pywa cloud start [--bot ] pywa cloud restart [--bot ] ``` See [Managing a Running Bot](/guides/lifecycle/) for what each one actually does, and what's automatic versus what needs you to act. `status` also makes a real request into a running bot (an unauthenticated GET, expecting pywa's own webhook challenge handler to answer 403) and prints whether it is serving — stronger proof of life than whether the process exists. Live CPU/memory usage, your plan's limits and request stats are in the dashboard. ## Connecting WhatsApp ```bash pywa cloud connect [--bot ] pywa cloud connect-status [--bot ] ``` See [Connecting a WhatsApp Number](/guides/connecting-whatsapp/). A WABA connection is a **team**-level resource, shared across every bot on the team — `connect` is the interactive entry point: it reuses a team's Meta Embedded Signup connection (or starts one), then assigns one of its phone numbers to the given bot, asking only when there is a real choice (a lone WABA or a lone number is used as is); the Embedded Signup link itself is single-use and expires after 15 minutes. `connect-status` shows whether (and to which WABA/phone) the bot is currently connected, including a warning if Meta has since flagged the underlying WABA as disconnected/restricted/banned. Assigning or clearing a number by id, connecting a WABA with your own Meta App token, and retrying a webhook that Meta refused are done in the dashboard. ## Database integrations Connecting a provider to your team and linking a database to a bot are done in the dashboard. See [Database Integrations](/guides/database-integrations/). ## Logs ```bash pywa cloud logs [--bot ] [--tail ] [--since ] [--follow] [--interval ] ``` See [Logs](/guides/logs/). `--tail` defaults to 200 lines; `--since` (RFC3339, e.g. `2024-01-01T00:00:00Z`) is a one-shot filter and is ignored together with `--tail` when combined with `--follow`, which manages its own cursor; `--follow` polls every `--interval` seconds (default 2.0) until Ctrl+C. ## Local development ```bash pywa dev --tunnel [--bot ] ``` The usual way to develop against real Meta webhooks: `pywa dev` (pywa's own local dev server) with `--tunnel` also relays this bot's inbound webhook traffic here instead of to its deployed version, so you don't need a separate tunnel tool or a repointed callback URL. `--bot` picks which Pywa Cloud bot to relay from (defaults to the current directory's linked bot). `--tunnel` also fetches this bot's real, live `PYWA_TOKEN`/`PYWA_PHONE_ID`/`PYWA_WABA_ID` and injects them into your local process's environment first, unconditionally — overwriting anything your project's own `.env`/hardcoded values set for those same three names — since relaying real webhooks to a process that can't send replies isn't a useful state to be in. Your bot's `pywa cloud env` variables and secrets are injected too, but never over a value you already set locally. See [Local Development](/guides/local-development/) for the full story. ```bash pywa cloud tunnel [--host ] [--port ] [--bot ] ``` The same relay as a standalone, foreground command — for pairing with anything other than `pywa dev` (a different framework runner, a manual process, etc.). `--host` (default `127.0.0.1`) and `--port` (default `8000`) are the address your own bot process is bound to. Opt-in and explicit either way: only active while the command is running; Ctrl+C (or any disconnect) hands traffic straight back to the deployed version. A dropped connection (network blip, sleep, a Pywa Cloud restart) is retried with backoff while the command runs; being replaced by a teammate's tunnel, stopped from the dashboard, or not being an admin ends it. If your machine goes silent for 45 s, Pywa Cloud drops the tunnel and the deployed version gets webhooks again. ## Environments ```bash pywa cloud demote [--bot ] [--yes] ``` A new bot is in `development`; only a development bot can be tunnelled (`pywa dev --tunnel`, `pywa cloud tunnel`) or have its credentials fetched for local use. Promoting it to `production` is done in the dashboard and ends a live tunnel. `demote` moves it back, asks for confirmation (`--yes` skips it) and is recorded in the audit log. Both need the admin role. Bots that existed before environments were introduced are in production. ## Deploy tokens (CI) ```bash pywa cloud deploy-tokens create [--expires-in-days ] [--bot ] # n: 1-365, default 90 pywa cloud deploy-tokens list [--bot ] pywa cloud deploy-tokens delete [--bot ] pywa cloud deploy-tokens regenerate [--expires-in-days ] [--bot ] ``` A deploy token is scoped to exactly one bot and can only be used for `deploy` — nothing else. The token value is shown once, at creation (or regeneration), and never again; losing it means `regenerate`, not looking it up. You can also manage tokens in the dashboard, under the bot's **Deploy tokens** tab (team admins and owners only). For CI, skip `pywa login` entirely: ```bash export PYWA_CLOUD_TOKEN= export PYWA_CLOUD_BOT_ID= pywa deploy ``` This bypasses your stored personal login completely — nothing CI runs ever touches it. `--bot` on `deploy` itself works too, instead of `PYWA_CLOUD_BOT_ID`. ## CI setup ```bash pywa cloud setup-ci [--bot ] [--branch ] [--force] ``` Scaffolds `.github/workflows/deploy.yml` in the current project, wiring up the deploy-token flow above as an automated on-push deploy. Reads repository secrets `PYWA_CLOUD_TOKEN` and `PYWA_CLOUD_BOT_ID` — add these under your repo's Settings → Secrets before the workflow can run. `--branch` defaults to whatever branch your project's own git checkout is currently on; `--force` overwrites an existing workflow file. The generated workflow installs both `pywa` and `pywa-cloud-cli` (`pywa` alone doesn't pull the cloud package in) and runs `pywa cloud deploy`. ## Not built yet Billing/usage metering — a business decision that hasn't been made yet, not just an unbuilt command. Teams, roles, and invites are fully implemented (see [Accounts, Teams & Permissions](/guides/accounts-and-teams/)) but don't have CLI commands of their own yet, since day-to-day account use rarely needs them — `pywa login`/`logout`/`whoami` above already cover the everyday auth surface. Pointing a [WhatsApp Flow](/guides/whatsapp-flows/) at a bot is also dashboard-only for now — there's no `pywa cloud flows ...` yet. Almost everything above also has a dashboard equivalent — deploying, env vars, logs, lifecycle (status/stop/start/restart/health), connecting WhatsApp, database integrations. The CLI isn't the only way to run Pywa Cloud, just the scriptable one; each guide linked from here says explicitly where the dashboard can or can't do the same thing.