Connect WhatsApp via Meta (Cloud API)

Goal

Walk through, step by step, how to connect a WhatsApp Business number to Helios directly via the Meta Cloud API, without intermediaries like Twilio.

Why Meta Cloud API over Twilio

• Lower cost: no middleman markup, just Meta's own pricing.
• Direct control: you manage your own app on Meta for Developers.
• Latest features first: immediate access to new WhatsApp API capabilities.

About Meta's "1,000 free conversations / month": this free tier exists, but it does NOT apply to AI-driven phone numbers. Meta classifies AI integrations as a paid use case, so even your test traffic counts. Without a payment method on file, Meta silently drops every inbound message — see Step 8.

Prerequisites

Before you start, make sure you have:

• A Meta for Developers account (free, can use your Facebook account).
• A Meta Business account (created automatically when you create an app, or you can use an existing one).
• A phone number for WhatsApp Business (must NOT be registered on regular WhatsApp; if it is, you must unlink it first).
• A valid payment method (credit card or debit card) you can attach to the WABA. Cost is trivial (~$0.005-$0.02 USD per conversation), but Meta requires it for AI numbers.
• Admin or owner access to your Helios tenant.
• An agent created in Helios with the WhatsApp channel enabled.

---

What Helios automates for you

Three configuration steps that historically caused new tenants to silently fail are now handled by Helios when you click Connect Number:

Helios does this automatically — you don't need to do it in Meta:

• Webhook URL is generated from your production domain (no manual construction).
• Verify Token is generated as a secure random string (hv_...).
• WABA-app subscription is registered against Meta's Graph API (POST /{waba_id}/subscribed_apps) so your app actually receives webhooks. This is the step that StackOverflow forgets.
• WABA ID auto-detection: if you only provide the Phone Number ID + Access Token, Helios queries Meta and fills the Business Account ID for you.

You still need to perform Steps 1-7 in Meta yourself (creating the app, adding the phone, generating the token, configuring the webhook URL/Token in the Meta dashboard). The two-level webhook concept is explained in Step 7.

---

Part 1: Setup in Meta

Step 1 — Create your Meta Business and developer account

1. Go to Meta Business Suite and create a Business account (skip if you already have one).
2. Go to Meta for Developers and log in with the same Facebook account that owns the Business.

Step 2 — Create an app in Meta for Developers

1. In Meta for Developers, click My Apps → Create App.
2. Choose app type Business.
3. Fill in:
   • App name: descriptive name (e.g. "MyCompany WhatsApp Bot").
   • Contact email: your business email.
   • Business portfolio: select an existing portfolio.
4. Click Create App.

Step 3 — Add the WhatsApp product and a phone number

1. After creating the app, you land on the dashboard.
2. In the left sidebar, open Use Cases and pick "Connect with customers through WhatsApp" → click Customize.
3. Select or create a WhatsApp Business Account (WABA):
   • If you already have one: select it.
   • If you don't: create one here, or create it in advance via Meta Business Suite → More tools → WhatsApp Manager.
4. Inside Customize, go to Production setup. This is the new home for everything you used to find under "API Setup" / "Configuration": the cards for Register your WhatsApp phone number, Configure Webhooks, and Add payment to send business-initiated messages all live here.
5. On the Register your WhatsApp phone number card, Meta auto-assigns a free test number you can use immediately. To use your own production number, click Add phone number, enter your business number, and verify with the SMS / voice code.

Note: The number you add cannot be registered on regular WhatsApp. If it is, uninstall WhatsApp from the phone and wait a few minutes before adding it here.

Step 4 — Create a permanent token (System User Token)

The temporary token shown in Production setup expires in ~24 hours. For production you need a System User Token:

1. Go to Meta Business Suite.
2. Click Settings → System Users.
3. Click Add to create a new system user:
   • Name: lowercase letters and underscores only (e.g. helios_whatsapp).
   • Role: Admin.
4. Once created, select the System User and click Add Assets:
   • Apps → choose your WhatsApp app → toggle Manage app (and Full Control if shown) → Save.
   • WhatsApp Accounts → ALSO add the WhatsApp Business Account as an asset and grant Full Control → Save. Without this, the connection step in Helios will fail with missing_permissions when it tries to bind the app to your WABA via Graph API.
5. Click Generate Token on that user.
6. Select your WhatsApp app and tick the permissions:
   • whatsapp_business_management
   • whatsapp_business_messaging
7. Click Generate Token and copy it. It's permanent, but only shown once.

Step 5 — Get the App Secret

1. In the left menu of your app on Meta, go to Settings → Basic.
2. Find App Secret, click Show, enter your Facebook password.
3. Copy the App Secret.

The App Secret allows Helios to verify that webhooks really come from Meta (HMAC-SHA256 signature). Highly recommended.

---

Part 2: Paste credentials in Helios

Step 6 — Connect the number in Helios

1. In Helios, go to WhatsApp in the sidebar.
2. Click Connect New Number → select Meta Cloud API.
3. Fill in:

4. Click Test Connection to verify (it returns the verified business name and quality rating).
5. Toggle Active if you want the number ready to receive messages.
6. Click Connect Number. At this point Helios calls Meta's Graph API to bind your app to the WABA — the silent webhook gap that broke many integrations in the past.

Note: If clicking "Connect Number" seems to do nothing, scroll up around the button — you may have a hidden validation error like missing Display Name or missing Assigned Agent.

Editing an existing Meta connection

• Encrypted credentials (Access Token and App Secret) show a "Saved" indicator — actual values are not displayed for security.
• You can keep them or replace them with new values.
• Test Connection works with stored credentials, no need to re-enter.

---

Part 3: Configure the webhook in Meta

Step 7 — Register the webhook URL

This is where Meta has two separate subscription levels, and confusing them costs people days of debugging:

1. App-level field subscription (you do this — Step 7).
2. WABA-level app subscription (Helios does this for you — see "What Helios automates for you").

Both must be in place for webhooks to arrive. Now configure the field-level subscription:

1. Go back to Meta for Developers, in your app.
2. In the left menu, open Use Cases → "Connect with customers through WhatsApp" → Customize → Production setup.
3. Find the Configure Webhooks card and click Configure (or Edit if it's already set up).
4. Fill in:
   • Callback URL: paste the Webhook URL shown in Helios (e.g. https://heliosvisionai.com/api/whatsapp/webhook).
   • Verify Token: paste the Webhook Verify Token from Helios (hv_...).
5. Click Verify and Save. Meta sends a GET to your URL to confirm the token matches.
6. Meta will normally subscribe the messages field for you in the background as part of this same step. If you want to double-check (5 seconds), open WhatsApp → Configuration → Webhook fields (the legacy page that exposes field-level toggles), find the messages row, and confirm it shows Subscribed (green). If it isn't, click Subscribe. While you're there, you can also subscribe message_status for delivery / read receipts.

If verification fails: confirm the URL is HTTPS, the domain is publicly reachable (not localhost), and the token matches exactly the one Helios generated.

---

Part 4: Payment method and publishing the app

These last two steps were undocumented for too long. Skipping either of them produces the exact same symptom: zero inbound messages, no error in the dashboard.

Step 8 — Add a payment method (mandatory for AI numbers)

Meta's "1,000 free conversations / month" tier explicitly excludes AI phone numbers. Without a payment method, Meta silently drops every inbound message — there is no error in the Meta dashboard, no rejection in Helios, just silence.

1. Go to Use Cases → "Connect with customers through WhatsApp" → Customize → Production setup.
2. Find the card labeled "Add payment to send business-initiated messages" (the wording also covers AI-initiated traffic).
3. Click Add payment method and enter your card.
4. Save.

Cost reality check: ~$0.005-$0.02 USD per conversation depending on country. A few cents covers extensive testing.

Step 9 — Publish the app (App Mode → Live)

Apps in Development mode never deliver real production webhooks — not even for app admins or testers. Meta's dashboard mentions this, but it's easy to miss.

1. In your app's left sidebar, click Dashboard.
2. Look for the panel "Check that all requirements are met, then publish your app".
3. Complete the basic requirements (Meta will list them):
   • Privacy Policy URL — required.
   • Terms of Service URL — required.
   • Data Deletion URL — required.
   • App Icon (1024x1024 PNG).
   • Category: "Business and Pages".
   • Business use description (a short paragraph about your use case).
4. Once requirements are met, the page redirects you to Publish, with the button now enabled. Click Publish.

Which URLs do I paste for Privacy / Terms / Data Deletion?

• Ideal: use your own legal pages if you already publish them (e.g. https://yourcompany.com/privacy). They name your business as the data controller, which is exactly what Meta wants to see.
• Fallback: Helios generates ready-to-use per-tenant legal pages for you at:
  • https://heliosvisionai.com/privacy/{your-slug}
  • https://heliosvisionai.com/terms/{your-slug}
  • https://heliosvisionai.com/data-deletion/{your-slug}

You can grab the exact URLs (with a one-click copy button) and edit your business name, contact info, address, and optional industry-specific clauses in Helios under Settings → Legal & Compliance. The same page also lets you override any of the three URLs with your own external link (Helios will 302-redirect Meta to it).

Why per-tenant URLs, not the platform /privacy: under GDPR/CCPA you are the data controller of your customers' data; Helios is only the data processor. Meta's app review expects the URLs to describe your business — name, contact, sensitive-data disclosures — not the underlying platform. The per-tenant URLs do exactly that; the platform-level https://heliosvisionai.com/privacy describes Helios itself and will not pass a tenant submission.

UX gotcha: clicking Publish in the left sidebar before completing the basic fields shows a disabled button with no clear next step. The path that actually works is Dashboard → Check requirements → fill fields → redirect to Publish.

No App Review required: WhatsApp Business Messaging does not need formal App Review. Live mode activates instantly once the basic fields are filled.

Step 10 — Click Connect Number

You already picked the agent and toggled Active at the top of this form, so the only thing left is to click Connect Number below. Helios will automatically subscribe this app to your WhatsApp Business Account so inbound messages reach the webhook — you do NOT need to do this in Meta. Send a test WhatsApp from another phone and your agent should reply within seconds.

If the message reaches Helios but no reply is generated, check:

• The assigned agent has the WhatsApp channel enabled.
• The agent has a system prompt configured.
• The server logs for processing errors.

---

Common silent failures (no error, no message)

These three are the usual suspects when "everything looks right but nothing arrives". Helios solves the third one for you, but the first two are still on you:

---

Connection error codes

When Helios fails to connect or bind your number, the modal shows one of these codes (returned by the server action as meta_bind:<code>):

---

Temporary vs Permanent Token

For production, always use a System User Token. If you use the temporary one, your integration will stop working when it expires.

---

Meta Cloud API costs

Meta charges per conversation (24-hour window), not per individual message:

See Meta's current pricing for your region.

---

Other common errors

---

Quick checklist

• Step 1: Meta Business + Meta for Developers account
• Step 2: Create app in Meta for Developers (Business type)
• Step 3: Add WhatsApp product, link a WABA, add phone number
• Step 4: Permanent System User Token with whatsapp_business_management + whatsapp_business_messaging (Full Control on App AND WhatsApp Account)
• Step 5: Copy App Secret from Settings → Basic
• Step 6: In Helios, paste credentials → Test Connection → Connect Number (Helios auto-binds the WABA)
• Step 7: In Meta (Use Cases → Connect with customers through WhatsApp → Customize → Production setup → Configure Webhooks), paste Webhook URL + Verify Token → Verify and Save → confirm messages is Subscribed under WhatsApp → Configuration → Webhook fields
• Step 8: Add payment method (mandatory for AI numbers)
• Step 9: Publish the app (Dashboard → Check requirements → Publish)
• Step 10: Click Connect Number in Helios (Helios auto-subscribes the app to your WABA), then send a test WhatsApp from another phone and confirm the agent replies

---

Related

• whatsapp — General WhatsApp manual (managing conversations, chat, notifications)
• twilio-setup — Alternative setup with Twilio
• integrations — General integrations