realvco Docs

Connecting WhatsApp

WhatsApp has 2 billion+ users worldwide — the top choice for cross-border business communication. But setup is more involved than Telegram. Read this page before starting to save yourself the missteps.

Two Paths — Pick One First

MethodBest ForDifficultyCostCaveats
QR Code PairingPersonal use, small team testing⭐ SimpleFreeUses a personal number; risk of ban
Business APIEnterprise, production commerce⭐⭐⭐⭐ Involved$0.005–$0.09 per messageBusiness entity + verification required

If this is for real commercial customer service, go straight to Business API. QR Code pairing uses a personal account. If Meta flags automation, it may ban the account and lock your personal WhatsApp.

Path A: QR Code Pairing (Personal Account)

Best for: personal use, rapid testing, small internal teams.

Prerequisites

  • A smartphone with WhatsApp
  • Strongly recommended: a secondary phone number (not your primary)

Steps

  1. Admin Panel → Ada (oc-2) tab → Settings → Messaging → WhatsApp
  2. Choose QR Code Pairing
  3. A QR code appears
  4. In WhatsApp on your phone → menu (⋮) → Linked Devices → Link a Device
  5. Scan the QR code with your phone camera
  6. Once paired, the Admin Panel shows “Connected”

[Screenshot: Admin Panel → WhatsApp → QR Code pairing screen]

After pairing, every message that phone number receives can be read and replied to by the AI.

  • Friends’ private messages will be too
  • Family group messages will be too
  • Hence the secondary-number recommendation

To pause AI replies: Admin Panel → Ada Dashboard → pause Messaging.

QR Pairing Limits

  • WhatsApp cap: one number can link up to 4 devices (including the phone itself)
  • The Admin Panel pairing consumes one of those slots
  • If the phone stays offline too long (~2 weeks), pairing expires and needs a new scan

Path B: Business API (Enterprise)

Best for: commercial customer service, cross-border sales, high message volume.

Prerequisites

You need:

  1. A registered business entity
  2. A Facebook Business Manager account
  3. A Meta Developer account
  4. A phone number not currently bound to another WhatsApp app
  5. A credit card (for API costs)

Plan for 2 to 5 business days (Meta review takes time).

Flow Overview

① Apply for a Meta Business Suite account
    ↓
② Create a Meta App (WhatsApp type)
    ↓
③ Add and verify a phone number
    ↓
④ Obtain a Permanent Access Token
    ↓
⑤ Retrieve Phone Number ID and Business Account ID
    ↓
⑥ Enter the above in the Admin Panel
    ↓
⑦ Set up the Webhook URL
    ↓
⑧ Start sending and receiving messages

Detailed Steps

  1. Apply for Meta Business Suite: go to business.facebook.com and create a business account

  2. Create a Meta App:

  3. Add a phone number:

    • WhatsApp → API Setup → Add phone number
    • Enter your business phone (must receive SMS or voice codes)
    • Complete Meta’s business verification (upload registration, representative info)

  4. Collect API credentials:

    • Permanent Access Token: Settings → System Users → create a System User and generate a Token
    • Phone Number ID: top of the API Setup page
    • WhatsApp Business Account ID: same location

  5. Configure in the Admin Panel:

    Ada Dashboard → Settings → Messaging → WhatsApp → Business API

    Fill in:

    • Access Token
    • Phone Number ID
    • WhatsApp Business Account ID

  6. Set up the Webhook:

    • The Admin Panel provides a Webhook URL like https://{your-prefix}-2.realvco.com/webhooks/whatsapp
    • Back in Meta Developer → WhatsApp → Configuration → Webhook
    • Paste the URL + the Verify Token (from the Admin Panel)
    • Subscribe to events: messages, message_template_status_update

[Screenshot: Meta Developer → WhatsApp → Configuration setup]

  1. Test:
    • Meta Developer → API Setup → send a test message to your WhatsApp
    • If you receive it and Ada replies → success

Business API Pricing

Meta charges per “conversation”:

  • Service conversations (user initiates): first 1,000 / month free, then roughly $0.005 / conv
  • Marketing conversations (you initiate): $0.02–$0.09 each (varies by country)
  • Taiwan, Hong Kong, Singapore sit mid-range
  • Full pricing: Meta WhatsApp Pricing

Advanced Configuration (Either Path)

The easiest approach: tell Rose what you want changed. Rose will configure it for you. Great for non-terminal users.

If you prefer the command line, SSH in and run the commands directly. Both paths shown below.

Access Control

Tell Rose:

“Only allow these numbers to message Ada on WhatsApp: +14155551234, +14155554321”

Or manually:

openclaw config set channels.whatsapp.dmPolicy "allowlist"
openclaw config set channels.whatsapp.allowFrom '["+14155551234", "+14155554321"]'

Group Rules

Tell Rose: “In the XXX group, Ada replies to every message — no @mention needed.”

Or manually:

openclaw config set channels.whatsapp.groups."*".requireMention true
openclaw config set channels.whatsapp.groups.GROUPID.requireMention false

Read Receipts

Tell Rose: “Enable read receipts for Ada’s WhatsApp.”

Or manually:

openclaw config set channels.whatsapp.sendReadReceipts true

Media Size Limit

Tell Rose: “Set Ada’s WhatsApp media limit to 50MB.”

Or manually:

openclaw config set channels.whatsapp.mediaMaxMb 50

Message Templates (Business API Only)

Business API requires pre-approved message templates to initiate conversations outside the 24-hour service window.

Submit in Meta Business Suite:

  1. WhatsApp Manager → Message Templates → Create
  2. Fill in category (Marketing / Utility / Authentication), language, content
  3. Submit for review (24–48 hours)
  4. After approval, enter the template ID in the Admin Panel — Ada can now use it

FAQ

Paired via QR, but AI Does Not Respond

  1. Does your phone’s WhatsApp “Linked Devices” show the connection as successful?
  2. Does Admin Panel → Ada → Messaging → WhatsApp show “Connected”?
  3. Is your phone online and has WhatsApp been opened recently?
  4. Try sending a message from a different number — does the AI reply?

Business API Webhook Verification Fails

Most common issues:

  • Verify Token typo (case-sensitive)
  • Webhook URL wrong (make sure it’s Ada’s -2 URL, not the Admin Panel’s -00)
  • The container is not running

Business API Application Rejected

Common reasons:

  • Incomplete business registration
  • Phone number previously bound to another WhatsApp app
  • Industry conflicts with WhatsApp Commerce Policy (crypto, gambling, adult content)

What If the Account Gets Banned?

QR pairing carries real risk. Warning signs:

  • Messages fail to send
  • “Violates terms of service” on login
  • WhatsApp app force-signs you out

Prevention:

  • Do not mass-send outbound messages
  • Do not run an AI spam bot
  • For real commerce, use Business API

Once banned, personal accounts are effectively unrecoverable. Switch to Business API.

Next Steps