realvco Docs

WhatsApp 連接教學

WhatsApp 全球用戶 20 億+，是跨國商業溝通首選。但設定比 Telegram 複雜。 先讀本頁再開始，省下踩雷時間。

兩種連接方式，先選一種

方式適合難度費用限制
QR Code 配對個人用、小團隊測試⭐ 簡單免費用私人號碼，有風控風險
Business API企業、正式商用⭐⭐⭐⭐ 繁瑣每則訊息美金 $0.005–$0.09要公司實體、認證

如果你是要做正式商用客服，直接走 Business API。
QR Code 方式用的是個人帳號，Meta 偵測到「疑似自動化行為」會封號，且你的私人 WhatsApp 會被鎖。

方式 A：QR Code 配對（個人帳號）

適合： 個人使用、快速測試、小團隊內部。

前置準備

  • 一支智慧型手機（有 WhatsApp）
  • 建議：準備一支備用號碼（不要用主力號碼）

步驟

  1. 管理儀表板（Admin Panel） → Ada (oc-2) Tab → 設定 → Messaging → WhatsApp
  2. 選 QR Code 配對
  3. 畫面上出現 QR Code
  4. 手機 WhatsApp → 選單（⋮）→ 連結的裝置 → 連結裝置
  5. 用手機相機掃 管理儀表板 上的 QR Code
  6. 配對完成，管理儀表板 顯示「Connected」

[截圖：管理儀表板 > WhatsApp > QR Code 配對畫面]

配對後，該 WhatsApp 號碼收到的訊息都會被 AI 讀取並可能被回覆。

  • 朋友的私人訊息也會
  • 家族群組的訊息也會
  • 因此強烈建議用備用號碼

如果要暫停 AI 回覆：管理儀表板 → Ada Dashboard → 暫停 Messaging。

QR 配對的限制

  • WhatsApp 限制：一個號碼最多連 4 個裝置（包含手機本身）
  • 管理儀表板 的配對會佔一個裝置名額
  • 手機離線太久（約 2 週）配對會失效，要重新掃 QR

方式 B：Business API（企業用）

適合： 正式商用客服、跨國銷售、大量訊息。

前置準備

你需要：

  1. 公司實體（有登記的商業體）
  2. Facebook Business Manager 帳號
  3. Meta Developer 帳號
  4. 不能已被綁在其他 WhatsApp 應用的電話號碼
  5. 信用卡（付 API 費用）

預計流程需要 2-5 個工作天（Meta 認證時間）。

流程總覽

① 申請 Meta Business Suite 帳號
    ↓
② 建立 Meta App（WhatsApp 類型）
    ↓
③ 加入電話號碼並驗證
    ↓
④ 取得 Permanent Access Token
    ↓
⑤ 拿到 Phone Number ID 和 Business Account ID
    ↓
⑥ 在 管理儀表板 填入上述資訊
    ↓
⑦ 設定 Webhook URL
    ↓
⑧ 開始收發訊息

詳細步驟

  1. 申請 Meta Business Suite：前往 business.facebook.com 建立企業帳號

  2. 建立 Meta App：

  3. 新增電話號碼：

    • WhatsApp > API Setup → Add phone number
    • 輸入要用的商業電話（必須能收 SMS 或電話驗證碼）
    • 完成 Meta 的企業認證（上傳營業登記、代表人資訊）

  4. 取得 API 認證：

    • Permanent Access Token：Settings → System Users → 建立 System User 並產生 Token
    • Phone Number ID：API Setup 頁面最上方
    • WhatsApp Business Account ID：同上

  5. 在 管理儀表板 設定：

    Ada Dashboard → 設定 → Messaging → WhatsApp → Business API

    填入：

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

  6. 設定 Webhook：

    • 管理儀表板 會給你一個 Webhook URL（形如 https://{前綴}-2.realvco.com/webhooks/whatsapp）
    • 回到 Meta Developer → WhatsApp → Configuration → Webhook
    • 貼上 URL + Verify Token（管理儀表板 提供）
    • 訂閱事件：messages、message_template_status_update

[截圖：Meta Developer > WhatsApp > Configuration 設定畫面]

  1. 測試：
    • Meta Developer → API Setup → 送測試訊息到你的 WhatsApp
    • 如果你收到，且 Ada 有回覆 → 成功

Business API 費用

Meta 按「對話」計費：

  • 服務對話（使用者先發起）：前 1000 次/月免費，之後約 $0.005/次
  • 行銷對話（你主動發起）：每次 $0.02–$0.09（依國家）
  • 台灣、香港、新加坡價格居中
  • 詳細費率：Meta WhatsApp Pricing

進階設定（兩種方式都適用）

最簡單的方式：告訴 Rose 你要改什麼，Rose 會幫你設定。 不熟終端機的人用這個方式。

熟悉指令的可以直接 SSH 進主機修改。以下各項都示範兩種做法。

存取控制

對 Rose 說：

「只允許這幾個號碼對 Ada WhatsApp 傳訊：+886912345678、+886987654321」

或手動：

openclaw config set channels.whatsapp.dmPolicy "allowlist"
openclaw config set channels.whatsapp.allowFrom '["+886912345678", "+886987654321"]'

群組規則

對 Rose 說：「XXX 群組裡 Ada 都要回覆，不用 @mention」

或手動：

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

已讀回條

對 Rose 說：「開啟 Ada WhatsApp 的已讀回條」

或手動：

openclaw config set channels.whatsapp.sendReadReceipts true

媒體大小限制

對 Rose 說：「把 Ada WhatsApp 的媒體檔上限設為 50MB」

或手動：

openclaw config set channels.whatsapp.mediaMaxMb 50

訊息範本（Business API 限定）

Business API 要主動發訊息給使用者（24 小時客服視窗外），必須用預先核准的訊息範本。

在 Meta Business Suite 建立並送審範本：

  1. WhatsApp Manager → Message Templates → Create
  2. 填寫類別（Marketing、Utility、Authentication）、語言、內容
  3. 送審（24-48 小時）
  4. 審核通過後在 管理儀表板 設定範本 ID，Ada 就可以使用

常見問題

QR 配對後 AI 不回應

  1. 手機 WhatsApp 的「連結的裝置」顯示連結成功？
  2. 管理儀表板 > Ada > Messaging > WhatsApp 狀態是「Connected」？
  3. 手機有開網路，且近期有打開 WhatsApp？
  4. 試著從另一個號碼傳訊息給你，看 AI 是否回覆

Business API Webhook 驗證失敗

最常見：

  • Verify Token 填錯（大小寫敏感）
  • Webhook URL 填錯（確認是 Ada 的 -2 URL，不是 管理儀表板 的 -00）
  • 容器當下沒跑起來

Business API 申請被拒

常見原因：

  • 營業登記不完整
  • 電話號碼之前被其他 WhatsApp 應用綁過
  • 行業類別與 WhatsApp 商業政策衝突（例如加密貨幣、賭博、成人內容）

帳號被封怎麼辦

QR 配對方式風險高。被封的徵兆：

  • 訊息送不出去
  • 登入時顯示「違反服務條款」
  • WhatsApp App 強制登出

預防：

  • 不要大量發送主動訊息
  • 不要把 AI 當垃圾訊息機器人用
  • 正式商用走 Business API

被封後個人帳號基本無解，建議改走 Business API。

下一步