Connect WhatsApp with Meta

Objective

Connect a WhatsApp Business number to Helios through Meta's official guided signup. You click Connect with WhatsApp, log in with Facebook inside Meta's popup, and finish in minutes. Helios is a Meta Tech Provider: the developer app, access tokens, webhook, and WhatsApp Business Account (WABA) subscription are all handled for you — you never open Meta for Developers. Only one step remains yours: adding a payment method in Meta so the number can send messages.

The manual setup path was retired. Creating a connection by hand — building a Meta app, generating a System User token, pasting a Phone Number ID and App Secret, configuring webhooks — is no longer available. Numbers connected that way in the past keep working and can still be edited; see "Edit an existing connection" below.

Access

Sidebar -> WhatsApp

Route: /app/{tenant}/whatsapp

Three entry points open the same flow: the Connect with WhatsApp button in the page header, the Connect Your First Number card when no number exists yet, and the Connect New Number row under the connected numbers list.

Roles

• View the WhatsApp page and conversations: owner, admin, agent (account must be active).
• Connect, edit, or delete a number: owner or admin only.
• A verified account email is required — connecting or editing is blocked until you verify it.

Prerequisites

• A plan that includes WhatsApp and available number capacity. Without it, the connect action opens an upgrade prompt.
• A Facebook account with access to your business's Meta Business portfolio. If you have no portfolio or WhatsApp Business Account yet, Meta's popup creates them during the flow.
• Depending on the option you pick (next section):
  • Use my own number: a phone number that can receive Meta's verification code by SMS or call, and that is not registered on the WhatsApp consumer or WhatsApp Business app — connecting it here removes it from those apps.
  • Use a Helios number: an active Helios phone number (see Phone Numbers).
• A payment method (credit or debit card) to add to your WhatsApp Business Account in Meta after connecting. Without it, Meta accepts the connection but the number cannot send messages.
• An active agent with the WhatsApp channel enabled, to assign after connecting — a number can only be set Active with an assignable agent.

Choose how to connect

Any connect entry point first runs the plan and email checks, then opens the How do you want to connect WhatsApp? dialog with two options:

If you have no Helios number, the second option is disabled and shows "You do not have a Helios number yet. Buy one first, then connect it to WhatsApp."

Pick an option and click Continue.

Connect your own number

1. In Meta's popup, log in with Facebook and follow the steps: select or create your Meta Business portfolio and WhatsApp Business Account, then enter your phone number.
2. Verify the number with the code Meta sends by SMS or voice call.
3. When the popup closes, the number appears under Connected Numbers in Helios.

Warning: the number is deregistered from the WhatsApp consumer/Business app and afterwards works only through the API. If the number is currently active on WhatsApp, Meta will not accept it — remove it from the app first, or pick a Helios number instead.

Connect a Helios number

1. Choose the number under Choose the number to connect and click Continue.
2. Meta's popup only asks you to share the WhatsApp Business Account — there is no number screen and no code to type.
3. Back in Helios, a progress card ("Connecting your Helios number to WhatsApp") tracks the registration: account linked, number added, waiting for Meta's verification code, code received, verified, registered, and finally "Your number is connected to WhatsApp." Most registrations finish within a couple of minutes; the code step depends on carrier SMS delivery.

If the card reports a failure:

If the card says it is taking longer than expected, the registration keeps running on our side — the number appears in the list below once it is ready.

Activate the number

New connections start Inactive and without an agent, so you decide who answers before any message is processed.

1. On the number's row, open the actions menu and click Edit.
2. Pick the Assigned Agent. Only active agents with the WhatsApp channel enabled are listed; with Teams enabled on your plan you can also pick a coordinator that answers as a team.
3. Tick Active (enable this connection) and click Save Changes.

You can also use the row's toggle — turning a number on requires an assignable agent, and if the linked agent went inactive the "Choose an active agent to reactivate" dialog asks you to pick a replacement.

Add your payment method in Meta

This is the one step the guided flow cannot do for you. Helios is a Meta Tech Provider, so you pay Meta directly for conversations — and Meta requires a payment method on your WhatsApp Business Account before the number can send anything. Meta reports no confirmation either way, so Helios treats a number that has never sent a message as unverified:

• The WhatsApp page shows a banner — "One step left: add your payment method in Meta" — naming the affected number.
• The number's row carries a Payment unverified chip, or Cannot send when Meta actually refused a send over billing.

To add it:

1. Open Meta Business Manager with the account you used to connect.
2. Go to WhatsApp Manager and open the billing or payment settings — the Open Meta billing button on the banner and on the number's row takes you straight there.
3. Add a payment method to your WhatsApp Business Account.

Back in Helios, click I have added it on the number's expanded row. The warning clears fully only once a message is actually delivered — Meta offers no way to check that a card exists, so real delivery is the only proof.

Cost: Meta bills your card per conversation, at rates that vary by country and category — see Meta's WhatsApp pricing. A few cents cover extensive testing.

Send a test message

Send a WhatsApp from another phone to the connected number. The agent should reply within seconds.

If the message reaches Helios but no reply is generated, check that the number is Active, that the assigned agent is active and has the WhatsApp channel enabled, and that the payment step above is done — a missing payment method fails silently, with no error anywhere.

Edit an existing connection

Open the actions menu on a number's row and click Edit:

Test Connection verifies the Phone Number ID and token against Meta — it works with the stored credentials, no re-entry needed. On success it shows Verified: followed by your business name (plus the quality rating when Meta returns one), and clears a stale Needs attention flag left by an earlier credential failure.

If saving fails with a Meta-side message (rejected token, missing permissions, account not found), the fastest fix for a guided connection is to reconnect: run Connect with WhatsApp again with the same number. Reconnecting refreshes the stored credentials and preserves the number's Active state and assigned agent. Numbers connected manually in the past can instead paste a fresh permanent token — the error message names the exact asset to fix.

Legacy Twilio connections: a connection created through the retired Twilio integration opens with the notice "This connection uses a retired setup method." Its credentials can no longer be edited, but you can still activate, deactivate, or delete it from the list. Twilio numbers themselves remain fully supported for voice.

Good practices

• Assign the agent and activate right after connecting — new numbers start Inactive on purpose, and nothing is answered until then.
• Add the payment method in Meta immediately after connecting. The failure mode without it is silence, not an error.
• Bring a dedicated business number, or use a Helios number — connecting your own number removes it from the WhatsApp app on your phone.
• To fix a Needs attention credential problem, reconnect with Connect with WhatsApp instead of deleting and re-adding: a reconnect keeps the Active state and the assigned agent.
• Run Test Connection in the edit modal after any credential change.

Common errors

Related

• WhatsApp — conversations, message templates, notifications
• Phone Numbers — buy the Helios number you can connect to WhatsApp
• Agents — enable the WhatsApp channel on an agent