Local Development
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.
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/<bot-id> - your bot’s opaque id -
registered once when you connect a WhatsApp number) - 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.
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 <bot-id>):
pywa dev --tunnel # runs your bot locally, injects its real WhatsApp credentials, and relays # this bot's webhook traffic hereInjected 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:8000Tunneling '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 <bot-id>
if the directory isn’t linked to one already.
Standalone tunnel — relay only, no credential injection
Section titled “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):
python main.py # or however you normally run it - note the port it's listening onThen, from the linked project directory (or with --bot <bot-id>):
pywa cloud tunnel --port 8000 # the port your bot above is listening onTunneling '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:8000POST /webhook -> 200What happens either way
Section titled “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
Section titled “A few things worth knowing”- Opt-in, not automatic. The tunnel is only active while
pywa dev --tunnel/pywa cloud tunnelis actually running - starting your bot locally on its own (plainpywa dev, orpython 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 logsor any other existing command.