Connect WhatsApp Business

Wassla connects to the WhatsApp Business Platform through Meta's standard OAuth flow. You click Connect on the WhatsApp tile, sign in to Facebook once, and approve the Wassla app's permissions. Meta sends you back to Wassla, and the server auto-discovers your WhatsApp Business Account, picks up the registered phone number, exchanges a long-lived access token, and registers the inbound webhook for you. The full round-trip takes about a minute and does not require you to touch the Meta developer console, paste an access token by hand, or configure a webhook URL.

Before you begin

A few prerequisites avoid the most common setup failures. Check each one before you click Connect.

  1. You must be an owner or admin of the Wassla workspace. The Connect button is hidden for support, finance, and viewer roles. Ask your workspace owner to do the connection if needed.
  2. Your workspace plan must include WhatsApp. The Free plan does not. If your plan does not include it, the OAuth round-trip will succeed on Meta's side but Wassla will redirect you back to the Channels page with a "Your current plan doesn't include WhatsApp" banner and an upgrade link. See Change your plan to upgrade.
  3. You must be an admin of the Meta Business Account that owns the WhatsApp Business Account (WABA) you want to use. If you sign in to Facebook with a personal account that has no admin role on the business, Wassla's auto-discovery step will return no WABAs and the connect will finish with no channel rows created.
  4. Your WABA must already have at least one phone number registered to it on the Meta side. Wassla picks up an existing registered number; it does not register a new SIM for you. If you have not yet onboarded a number to the WhatsApp Business Platform, do that in the WhatsApp Manager at business.facebook.com first.
  5. Make sure the agent that should handle WhatsApp traffic is published. Draft agents are skipped by the inbound webhook handler. See Train your AI agent for publishing steps.

Connect WhatsApp through Facebook

Wassla never asks you for your WhatsApp password, access token, or webhook URL. The connection happens through Meta's hosted authorization dialog, and the long-lived access token is stored server-side and never shown back in the UI.

  1. In Wassla, open Channels from the left sidebar (Inbound tab).
  2. Find the WhatsApp tile (green chat-bubble glyph) and click Connect. The browser redirects to facebook.com/v21.0/dialog/oauth.
  3. Sign in to Facebook with the account that admins your Meta Business. If you stay signed in on this browser, future reconnects skip this step.
  4. On the "Wassla would like to" permission screen, leave every permission checked. Wassla requests whatsapp_business_management and whatsapp_business_messaging for the WhatsApp connection, plus Instagram and Page-scoped permissions (instagram_basic, instagram_manage_messages, instagram_manage_comments, pages_show_list, pages_messaging, pages_manage_metadata, pages_read_engagement, business_management, public_profile) so the same sign-in can also pick up Instagram DMs and Facebook Page Messenger if those assets exist on the same business. Granting only some of the permissions will cause discovery to fall back to "no assets found" for the missing channels.
  5. Click Continue. Meta redirects to Wassla's callback endpoint, which finishes the token exchange in the background and then redirects you to /channels?connected=whatsapp (other connected channels are appended to the same query string). A green "Connected" banner appears on the Channels page, and the WhatsApp tile now shows your display phone number underneath the channel name.

If something fails during the redirect, Wassla shows the upstream error code at the top of the Channels page. The most common one is feature_not_in_plan, which means your workspace plan does not include WhatsApp. The next most common is token_exchange_failed, which usually means your Meta session expired mid-flow — click Try connecting again. state_expired means more than ten minutes passed between starting the flow and returning from Facebook — just start over.

What Wassla stores under the hood

For technical readers, here is exactly what the OAuth callback discovers via Meta's Graph API and writes to the whatsapp channel row, so you know what to ask Meta support about if anything looks wrong:

  • WABA ID (waba_id) — your WhatsApp Business Account identifier, fetched from /me/businesses?fields=owned_whatsapp_business_accounts. Used for template management and number administration. Wassla uses the first WABA the admin's Meta Business owns; multi-WABA picking is not exposed in the UI.
  • Phone number ID (phone_number_id) — the per-number identifier the Graph API uses to send outbound messages and which arrives on every inbound webhook payload. Fetched from /{waba_id}/phone_numbers. Wassla uses this to resolve the inbound message to your tenant. If multiple numbers are registered to the WABA, Wassla picks the first one returned by Meta.
  • Long-lived access token — exchanged from the short-lived OAuth code via the fb_exchange_token grant, then stored in agent_channels.config and never returned by the /status endpoint.
  • Display phone number — the human-readable E.164 number shown to customers. It surfaces in the channel tile subtitle and in the Inbox conversation header.
  • Two-step verification PIN (wa_pin) — Wassla auto-generates a six-digit PIN server-side and stores it alongside the token so the number cannot be silently re-registered elsewhere. You are not asked to enter or remember this PIN; it is never displayed in the UI.

You do not need to record any of these values yourself. They are visible in summary form (without the token or PIN) on the Manage modal for the WhatsApp tile.

Verify inbound delivery

Wassla auto-subscribes the inbound webhook with Meta during connect, but you should confirm the first real message round-trip before relying on the integration.

  1. From a phone that is not the business number itself, send a WhatsApp message to your business number. Messages sent from the business number to itself are not delivered.
  2. Open Inbox in Wassla. The conversation should appear within five seconds with a WhatsApp (green) channel badge.
  3. Confirm the AI agent replied. If the reply lands in WhatsApp on the sender's phone, the integration is live end-to-end.
  4. If nothing arrives, see Troubleshoot a channel that stops delivering.

After connect: WhatsApp Calling

Once WhatsApp chat is connected, a separate WhatsApp Call card appears underneath the channel grid. WhatsApp Calling rides on the same phone number and access token, but it is a separate enable step because not every workspace wants voice. Pick a voice-capable agent from the dropdown and click Connect WhatsApp Call to let customers tap the call button in your WhatsApp profile and reach the AI voice agent. See Voice vs text agents for what voice agents can and cannot do.

If you later disconnect WhatsApp chat, Wassla automatically disables WhatsApp Calling at the same time so it does not become an orphan.

Picking a specific WABA or phone number

Wassla today connects whatever Meta returns first for the signed-in admin: the first WABA on the first business, and the first phone number on that WABA. If your business owns multiple WABAs, or one WABA has multiple registered numbers, and Wassla picks the wrong one, the workaround is to ensure the desired WABA/number is the only one (or the first one) listed under the Meta Business the admin signs in with. In-app multi-asset picking is not part of the current release; please contact support if you need it.

Revoking the connection

To disconnect WhatsApp, open the WhatsApp tile on the Channels page, click Manage, and then click Disconnect in the channel detail modal. Wassla immediately deletes the channel row and stops processing inbound webhooks for that phone number. New inbound messages are dropped before any AI spend is incurred.

Disconnecting in Wassla does not remove the Wassla app permission on the Meta side. To fully revoke access on Facebook's side, go to Settings and privacy → Settings → Business integrations on facebook.com and remove Wassla from the list. You can also rotate the access token by simply reconnecting — the upsert path overwrites the old token with the new long-lived one.