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

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

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://<your control plane>/teams/<team-id>/connect/<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 Connect WhatsApp 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.

Pywa Cloud then saves PYWA_TOKEN, PYWA_PHONE_ID, PYWA_WABA_ID, and PYWA_VERIFY_TOKEN for this bot (the token and verify token as secrets — 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’s control plane registers the webhook callback for you, server-side, right after your next successful deploy.

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.

Using the connection in your code

Read the values Pywa Cloud injected, exactly like every other pywa example:

import os
from pywa import WhatsApp

wa = WhatsApp(
    phone_id=os.environ["PYWA_PHONE_ID"],
    token=os.environ["PYWA_TOKEN"],
    verify_token=os.environ["PYWA_VERIFY_TOKEN"],
)

Don’t pass callback_url/callback_url_scope - leave them unset. Pywa Cloud’s control plane registers your bot’s webhook callback for you server-side once your deployment is healthy, so pywa never needs to self-register one. (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.)

Assigning or disconnecting a number without the interactive prompt

For scripting or CI, skip straight to a known WABA connection and phone number instead of running the interactive picker:

pywa cloud waba list
# conn_abc123  987654321            embedded_signup  active

pywa cloud whatsapp assign conn_abc123 123456789
pywa cloud whatsapp disconnect

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 instead of running Embedded Signup:

pywa cloud waba connect-manual <waba-id> <business-token> --app-secret <optional-app-secret>

This validates the token by listing the WABA’s phone numbers before saving anything - a bad token fails immediately. --app-secret is optional: if given, Pywa Cloud’s ingress uses it to validate this connection’s inbound webhook signatures, same as the platform-owned path; if omitted, that validation is skipped for every bot assigned a number from this connection, and both the CLI and dashboard show a persistent warning rather than a silent gap. Once connected, assigning a phone number to a bot (pywa cloud connect or whatsapp assign) 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.

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’s container, 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 picks up the refreshed token automatically, with nothing else to change. 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.