v1.0 live! Celebrating with 50% off -limited offer
-
Get Started

Whatsapp Business Connection Guide

WhatsApp Business Connection Guide

Connect your own WhatsApp Business account to DIMA-AI through Meta's official WhatsApp Cloud API. Once linked, the WhatsApp Messenger Agent can send text, media, and approved template messages on your behalf — directly from a chat or workflow.

> Important. DIMA does not provide a shared WhatsApp number. Each user connects their own Meta WhatsApp Business account. We never see, store, or proxy traffic for any number that isn't yours.

What you need before starting

  • A Meta (Facebook) account that owns or has admin access to a Meta Business Portfolio.
  • A Meta Business Portfolio (Business Manager). If you don't have one, create it for free at <https://business.facebook.com/>.
  • A phone number you control. It must not currently be registered with the regular WhatsApp or WhatsApp Business mobile apps. If it is, uninstall WhatsApp from that number first or use a fresh number. (For testing, Meta gives you a free test number — no setup required.)
  • About 5–10 minutes.

Why personal WhatsApp (QR code) is not supported

Some agents on the internet try to link standard, non-Business WhatsApp accounts by running a hidden browser that scans a QR code. We deliberately do not do that, for three reasons:

  1. It violates WhatsApp's Terms of Service. Meta routinely bans numbers that connect through unofficial Web automation. We refuse to put your personal number at risk.
  2. It cannot run reliably on a cloud deployment. Each linked account would need a dedicated headless browser, which dies on every restart and doesn't survive scaling.
  3. It is insecure. The QR payload that authenticates the session is highly sensitive and would have to leave your device.

The path below — Meta's official WhatsApp Business Cloud API — is the only supported, safe, and Meta-sanctioned way to connect.

Step 1 — Create (or open) a Meta App

  1. Go to <https://developers.facebook.com/apps/> and sign in with the Meta account that has admin rights on your Business Portfolio.
  2. Click Create App (skip if you already have one suitable).
  3. Choose use case: Other → click Next.
  4. Choose app type: Business → click Next.
  5. Enter:

- App name (anything you like — e.g. "Acme WhatsApp") - Business Portfolio — select the one your number belongs to.

  1. Click Create App and complete the security check.

You'll land on the Meta App Dashboard for the new app.

Step 2 — Add the WhatsApp product

  1. In the left sidebar of the App Dashboard, scroll down and click + Add Product.
  2. Find WhatsApp in the product list and click Set up.
  3. Confirm or select your Business Portfolio when prompted.
  4. Meta now creates a WhatsApp Business Account (WABA) and provisions a free test phone number linked to your app.

You should now see a new sidebar group called WhatsApp with API Setup under it.

Step 3 — Copy your Phone Number ID

  1. In the sidebar: WhatsApp → API Setup.
  2. Locate the section Send and receive messages.
  3. Under From, you'll see the Phone number ID — a long numeric value such as 123456789012345.
  4. Click the copy icon next to it.

> The "From" phone number itself is not what you need; what you paste into DIMA is the Phone number ID.

Step 4 — Get an Access Token

You have two choices. Pick A for quick testing, or B for production. We strongly recommend B for any real use.

Option A — Temporary token (good for 24 hours, testing only)

  1. Still on the WhatsApp → API Setup page.
  2. At the top of the page, copy the Temporary access token.
  3. This token expires automatically in 24 hours. Use it only to verify the setup works.

A System User token is the production-grade credential. It does not expire by default and survives Meta password resets.

  1. Open Meta Business Suite at <https://business.facebook.com/>.
  2. Click the gear icon (Settings) → Business settings.
  3. In the left sidebar: Users → System users.
  4. Click Add → enter a name (e.g. "DIMA WhatsApp Sender") → role: Admin → Create system user.
  5. With the new system user selected, click Add assets:

- Asset type: Apps — select your Meta App and grant Develop app + Manage app. - Asset type: WhatsApp accounts — select the WABA created in Step 2 and grant Full control.

  1. Click Generate new token at the top of the system user's page.
  2. In the dialog:

- App — select your Meta App. - Token expiration — choose Never. - Permissions (scopes) — tick both: - whatsappbusinessmessaging - whatsappbusinessmanagement

  1. Click Generate token, copy the token immediately, and store it somewhere safe. Meta will not show it again.

Step 5 — Paste the credentials into DIMA

  1. In DIMA, open the workspace where the WhatsApp Messenger Agent is installed (or install it from the Marketplace first).
  2. Open the agent's Settings panel (gear icon next to the agent, or the per-step config in a workflow).
  3. Fill in:

- Phone Number ID — paste the value from Step 3. - Access Token — paste the token from Step 4. - Graph API Version — leave at the default (v21.0) unless you specifically need another version.

  1. Click Save.

> Both fields are stored encrypted in your DIMA workspace settings and are never exposed to the model in chat.

Step 6 — Verify the connection

  1. Open a chat with the WhatsApp Messenger Agent.
  2. Send: "check my whatsapp connection" (or run the wapp-connect skill).
  3. The agent calls Meta's API and returns:

- Verified name — your business display name (or Unverified if you haven't completed Meta business verification yet). - Display phone number — the number Meta will deliver from. - Quality rating — GREEN, YELLOW, or RED. New numbers start at GREEN. - Messaging tier — your daily messaging cap (TIER50, TIER250, TIER1K, TIER10K, TIER100K, TIERUNLIMITED). - Approved templates — the list of message templates you can send outside the 24-hour customer service window.

If you see all of those, you're done. The agent is ready to send messages.

Step 7 — Send your first message

Inside the 24-hour customer service window

If the recipient has messaged your business in the last 24 hours, you can send any free-form text or media:

> "Send a WhatsApp message to +14155551234 saying 'Thanks for reaching out — we'll be in touch soon.'"

Outside the 24-hour window (or to brand-new contacts)

You must use an approved message template. New WABAs ship with at least one default template (helloworld):

> "Send the WhatsApp template helloworld in enUS to +14155551234."

To create your own templates:

Open Meta Business Suite → WhatsApp Manager → Message templates → Create template.Templates are reviewed by Meta within minutes to a few hours.Once approved, the agent will see them automatically the next time you run wapp-connect.

Going live: from test number to your real number

The free test number from Step 2 only sends to phone numbers you explicitly add to a small allow-list in the API Setup page. To send to anyone, you need to add and verify your own phone number:

WhatsApp → API Setup → click Add phone number.Enter your business phone number (the one that will appear in WhatsApp).Verify it via SMS or voice call.Complete Display name review (Meta typically approves in a few hours).Optionally complete Business verification in Business Settings → Security Center to lift messaging limits and unlock the green checkmark.Once your real number is approved, copy its Phone number ID and replace the test number ID in DIMA's agent settings.

Troubleshooting

"Access Token is invalid or expired" (Meta code 190)

The temporary token expires after 24 hours — generate a System User token (Step 4 → Option B).Or the System User no longer has the required app/WABA assets — re-add them and regenerate the token.

"Access Token is missing required permissions" (Meta code 200)

  1. The System User token was generated without whatsappbusinessmessaging or whatsappbusinessmanagement. Regenerate the token and tick both scopes.

"Recipient phone number not in allowed list" (Meta code 131030)

You're still using the test number. Either add the recipient to the allow-list on the API Setup page, or migrate to your own verified number (see "Going live" above).

"You can only send messages within 24 hours of the user's last message" (Meta code 131047 / 131051)

  1. The recipient hasn't messaged you, or the last inbound message is more than 24 hours old. You must send an approved template instead. Use the templatename and template_language parameters when asking the agent to send.

"Phone Number ID looks invalid"

  1. Paste the Phone number ID (a numeric value), not the phone number itself, not the WABA ID, and not the App ID. Find it on WhatsApp → API Setup under From → Phone number ID.

"Quality rating is RED"

  1. Meta has flagged your number for spam or low-quality messaging. The agent will refuse bulk sends to protect you. Slow down, only message users who have explicitly opted in, and use approved templates. The rating recovers over a few days of healthy usage.

Limits to be aware of

The WhatsApp Business Cloud API is messaging-only. It does not support:

  1. Reading historical chat messages (inbound messages are delivered to your own webhook in real time, not pulled).
  2. Group messaging or group management.
  3. Listing your contacts.
  4. Built-in chat analytics.

The DIMA WhatsApp Messenger Agent therefore exposes:

  1. wapp-connect — validate credentials and list templates.
  2. wapp-status — health check.
  3. wapp-send-message — text, media, or template.
  4. wapp-contacts — phone-number format validation.

If you need full inbound + analytics, you'll want to set up a webhook receiver (separate, optional integration). Reach out to support if you need help with that.

Security notes

  1. DIMA stores your Phone Number ID and Access Token encrypted in the workspace settings only. They are never exposed to the language model in chat.
  2. All calls go to graph.facebook.com over HTTPS. The agent's API client refuses to call any other host.
  3. Rotate your System User token immediately if you ever suspect it leaked. Old tokens can be revoked from Meta Business Suite → Business Settings → Users → System Users → Revoke.
  1. Meta App Dashboard: <https://developers.facebook.com/apps/>
  2. Meta Business Suite: <https://business.facebook.com/>
  3. Cloud API getting-started (official): <https://developers.facebook.com/docs/whatsapp/cloud-api/get-started>
  4. Cloud API reference: <https://developers.facebook.com/docs/whatsapp/cloud-api>
  5. Message templates guide: <https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates>
  6. WhatsApp Manager (templates UI): <https://business.facebook.com/wa/manage/>