Connecting a WhatsApp Number
Pywa Cloud is a Meta Tech Provider — 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 — 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
Section titled “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 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 instead.
Connect a number
Section titled “Connect a number”pywa cloud connectThis 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/<team-id>/<session>
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> 1Either 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:
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 below), connect-status surfaces it:
pywa cloud connect-status# 🟢 connected (WABA: 987654321, phone: 123456789, since 2026-09-03T12:14:02Z)# ⚠️ underlying WABA connection is restricted - <Meta's own remediation message>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
Section titled “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
Section titled “Using the connection in your code”Read the values Pywa Cloud injected, exactly like every other pywa example:
import osfrom 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
Section titled “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:
curl -X POST "https://graph.facebook.com/v26.0/<PHONE_NUMBER_ID>" \ -H "Authorization: Bearer <TOKEN>" -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
Section titled “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 ownPYWA_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 bypywaserver-side once your webhook is registered - nothing extra to do.
Connection status changes
Section titled “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
Section titled “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 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 <the-bot's-own-current-deployment-id> (find it with
pywa cloud deployments list --bot <bot-id>) - same underlying action the dashboard’s button
calls, just without a dedicated shortcut command yet.