# 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.