Connecting WhatsApp

Connect a WhatsApp Business Account via the console or platform setup links, then confirm with webhooks.

Before you can send, a workspace needs a connected WhatsApp number. LazyApp is WhatsApp-only — there is no multi-network OAuth catalogue. Connection always goes through Meta Embedded Signup; you never collect access tokens yourself.

How to think about it

• Own workspace: connect from the LazyApp console (Embedded Signup). Connecting your own number needs a plan, and each plan includes a set number of numbers; the shared test number is free.
• Meta bills messages, not LazyApp. Add a payment method to the WhatsApp Business Account in Meta. Meta charges it at Meta’s rates, and LazyApp adds 0%. See Meta message billing.
• Your customers’ numbers: use setup links so each platform customer connects into their own workspace.
• Confirm from webhooks (connection.connected / customer.connected), not from the browser redirect alone.
• After connect, read capabilities for that number — calling, messaging limits, and quality are per connection.

Console Embedded Signup

For your own workspace:

1. Open Connections in the LazyApp console.
2. Start Connect WhatsApp (Meta Embedded Signup).
3. Finish Meta’s screens (Business Portfolio, WABA, phone number).
4. LazyApp stores the connection on the current workspace and mode (live / test).

During onboarding you can also paste existing Meta credentials (phone number ID, WABA ID, system-user token) in the console. That path is not exposed as a public API endpoint — platform integrations should use setup links instead.

Subscribe to:

Event	When
connection.connected	The number is ready to send
connection.attention_required	Meta needs action (review, credentials)
connection.disconnected	The link to Meta stopped working

There is no public GET /v1/connect/{platform} OAuth starter for Twitter/Facebook/etc. — that Zernio-style surface does not apply here. There is also no public POST /v1/connect/whatsapp/credentials — use Embedded Signup or setup links.

Details filled in for you

When your workspace has a name, a website and a time zone (and you have a billing email or a login email), LazyApp sends them to Meta so the business portfolio screen arrives filled in. Meta only uses them when all four are present; the person signing up can still edit every field.

Finishing without a phone number

A business can share or create a WhatsApp account in Meta’s window and skip adding a number. LazyApp still connects the account and then asks which number to send from: pick one already on the account, or add a new one (country code, number, and the name customers will see). LazyApp holds the account for one hour while you choose. A new number then needs a verification code and registration; see Phone numbers.

When Meta’s window closes early

If the person closes Meta’s window, LazyApp shows which step they stopped at (choosing the business, the WhatsApp account, the number, the code or the permissions) and what to do next. If Meta showed an error, LazyApp repeats Meta’s message with the error code and session id to quote to support.

While Meta is still reviewing LazyApp’s app (App Review for whatsapp_business_management and whatsapp_business_messaging), Embedded Signup only completes for businesses LazyApp has added as testers. Until then, connect with Paste details from Meta using your own system-user token.

WhatsApp Business app coexistence

Businesses already on the WhatsApp Business app can connect the same number to Cloud API without giving up the app. During Embedded Signup, Meta offers Connect existing WhatsApp Business app account. LazyApp marks the connection as coexistence and requests contact and history sync from Meta.

When coexistence is active:

• Messages can mirror between the app and Cloud API (Meta syncs up to about six months of history).
• Contacts from the app are imported via Meta’s smb_app_state_sync webhooks.
• Outbound messages sent from the phone app arrive as message.received with an echo flag — treat them like inbound for inbox UX.
• Revokes in the app emit message.deleted for the original stored message.

LazyApp-specific: coexistence numbers report flows: false and flows.data_endpoint: false on GET /v1/capabilities. Plan Flow-based onboarding for Cloud-API-only numbers.

Meta limitations (same on every BSP):

Feature	Coexistence
Throughput	Fixed at 20 messages per second
Deregistering	Not allowed while the app still uses the number
Group chats (app-side)	App groups are not visible via API
Groups API	Not supported on coexistence — use a Cloud-API-only number; see Group chats
Voice/video calls via API	Not supported
Disappearing / view-once messages	Disabled for 1:1 Cloud API chats
Broadcast lists in the app	Disabled

History sync window: LazyApp requests sync immediately after signup. Meta allows about 24 hours to complete it. If sync never starts, the customer may need to disconnect and run Embedded Signup again.

Disconnection: The business disconnects from the WhatsApp Business app (Settings → Account → Business Platform → Disconnect). That cannot be done via API. Meta notifies LazyApp; the connection moves to a disconnected state and connection.disconnected fires. Treat webhook absence as inconclusive — poll GET /v1/capabilities when you need to confirm liveness.

Coexistence uses the same send and webhook endpoints as a standard Cloud API number. The practical differences are throughput, Flows being off, and read-state quirks when the phone app owns blue ticks.

Platform customers (white-label)

When each of your users brings their own WhatsApp number:

1. Create a platform customer.
2. Create a setup link with their customer_id and your redirect_url.
3. Send them the returned url (email or Connect WhatsApp button).
4. Confirm with customer.connected (and setup_link.failed on failure).

curl https://lazyapp.in/v1/platform/setup-links \
  -H "Authorization: Bearer $LAZYAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_9f8b1c2d",
    "expires_in_days": 7,
    "use_policy": "single",
    "allowed_connection_type": "new",
    "redirect_url": "https://yourapp.example/settings/whatsapp?connected=1"
  }'

Headless vs hosted

LazyApp hosts the connect UI at /connect/{token}. You do not build a Meta page picker yourself — WhatsApp Embedded Signup selects the WABA and number inside Meta’s flow. Set a public connect host in Branding when that URL should use your domain. The host must proxy /connect to LazyApp.

Optional per-link success_webhook_url / failure_webhook_url fire in addition to your workspace webhooks. Still treat them as secondary to customer.connected / setup_link.failed.

Reconnect

When connection.disconnected or connection.attention_required fires for a customer, issue a new setup link with allowed_connection_type: "reconnect" (or either) and prompt them in your UI. Details in setup links.

After connect

1. GET /v1/capabilities — confirm the number is listed and which features Meta granted.
2. Send a template or session message (quickstart).
3. Register webhooks for delivery and inbound (webhooks).

Coexistence (WhatsApp Business app + Cloud API on the same number) is supported when Meta’s onboarding path allows it — see WhatsApp Business app coexistence above for limits and webhook behaviour.

Related

• WhatsApp overview — quick reference and doc map
• Setup links — create, options, revoke
• Build a platform — customer model and webhook routing
• Capabilities — what the connected number can do
• Event reference — connection.* and customer.connected