接入 WhatsApp

Buda 透過掃碼配對的方式連接 WhatsApp，底層使用 Baileys 函式庫，原理與 WhatsApp Web 相同。這意味著無需 Meta 企業帳號、無需申請手機號 API、也無需任何付費訂閱。只需用手機掃一下 QR Code，Buda 就會在背景自動維持連線。

需要兩個帳號：您需要一個 WhatsApp 帳號作為機器人（帳號 A，綁定到 Buda），以及另一個帳號向它傳送訊息（帳號 B）。WhatsApp 會過濾掉帳號自己傳給自己的訊息。

步驟 1：在 Buda 中新增 WhatsApp 頻道

1. 開啟 Buda 的頻道設定（Channels）（設定 → Channels）。
2. 點擊新增頻道，提供商選擇 WhatsApp。
3. 可選填寫標籤（例如：我的 WhatsApp 機器人）並選擇目標 Agent。
4. 點擊連接 — 頁面上會顯示一個 QR Code。

步驟 2：掃描 QR Code

1. 在手機上開啟 WhatsApp（帳號 A）。
2. 進入設定 → 已關聯裝置 → 關聯裝置。
3. 將鏡頭對準 Buda 頁面上顯示的 QR Code。
4. 掃碼成功後，狀態會變為 Active，QR Code 隨即消失。

伺服器日誌中會出現：

[whatsapp] Connection open for channel <id>

步驟 3：開始使用

• 私訊：用帳號 B 直接向帳號 A 的手機號傳送訊息，Buda 會收到並透過設定的 Agent 回覆。
• 群組：將帳號 A 加入 WhatsApp 群組，群內任意訊息都會被 Buda 處理，無需 @ 提及。

注意事項

• 無需 HTTPS：掃碼配對完全在本機開發環境中執行，無需公網位址或 Webhook 設定。
• 需要兩個帳號：必須使用另一個 WhatsApp 帳號（帳號 B）向機器人帳號（帳號 A）傳送訊息。帳號 A 傳給自己的訊息會被忽略。
• 會話持久化：認證憑證儲存在伺服器的 .data/whatsapp/<channelId>/ 目錄下，重啟後會話依然有效，只需掃碼一次。
• 自動重連：連線斷開後，Buda 會以指數退避策略自動重試。若會話過期，頻道設定頁面會重新顯示 QR Code。
• 群組模式：與 Telegram 不同，WhatsApp 群組無需 @ 提及機器人，群內所有訊息都會轉發給 Agent 處理。
• fromMe 過濾：帳號 A 自身傳出的訊息（例如從其他已關聯裝置傳送的）會被自動忽略，防止訊息迴圈。