用 Vercel AI SDK 建立 WhatsApp 智能代理

路由處理器如何接收 WhatsApp 訊息？

在同一個路由上實作兩個方法，並把它設為該號碼的 Webhook 目的地，路徑中加入一段很長的隨機密鑰。

GET 用來回應 Meta 的驗證。從查詢字串讀取 hub.mode、hub.verify_token 和 hub.challenge，比對權杖後，以純文字回傳 challenge。常見的錯誤是用 JSON 輔助函式回傳：內容會被加上引號，Meta 便不會開始傳送事件。

POST 用來接收事件。請盡快回傳 200，之後才呼叫模型。Meta 會重試過慢的回應，若冷啟動時在請求內直接執行模型，同一則訊息可能被回覆兩次。如果平台在送出回應後就結束函式，請把工作交給佇列，或使用平台提供的回應後處理機制。

路徑中的密鑰就是驗證手段。Meta 以 Tech Provider 的應用程式密鑰簽署每次傳送，因此您這一端無法檢查 X-Hub-Signature-256 標頭。

AI SDK 如何載入 WhatsApp 工具？

使用 @ai-sdk/mcp 的 createMCPClient 和 HTTP 傳輸層，AI SDK 文件建議在正式環境採用這種方式。傳輸層需要伺服器 URL 和 authProvider，EasyCoexistence MCP 伺服器就是透過 authProvider 以 OAuth 授權：它公開 OAuth 中繼資料，支援動態用戶端註冊和 PKCE，並在登入後自行簽發權杖。您不需要在標頭中放入 API 金鑰。

用戶端提供的工具可直接交給 generateText 或 streamText。模型隨即看到 list_numbers、send_message、send_template、get_number_health 等工具，說明中都註明 24 小時視窗。呼叫完成後請關閉用戶端：串流在 onEnd 回呼中關閉，其他情況在 finally 區塊中關閉，這也是 AI SDK 文件的要求。

適合由模型自行決定的情況。若只是回覆剛收到的訊息，在處理器中直接呼叫 Cloud API 會更簡短。

import { createMCPClient } from "@ai-sdk/mcp";

const mcp = await createMCPClient({
  transport: {
    type: "http",
    url: "https://easycoexistence.com/api/mcp",
    authProvider, // your OAuthClientProvider implementation
  },
});

try {
  const tools = await mcp.tools();
  // pass tools to generateText({ model, tools, prompt })
} finally {
  await mcp.close();
}

號碼使用 Coexistence 後有什麼不同？

程式需要留意兩點。第一，對話中可能已有真人。WhatsApp Business 應用程式在該號碼上照常運作，在手機上輸入的每則回覆，都會以 echo 事件送到路由。處理器若在收到 echo 後暫停對該聯絡人使用模型，就不會搶在真人之前回覆。

第二，該號碼的傳送速率固定上限為每秒 20 則訊息。對話式代理不會接近這個數字，但用 Promise.all 對聯絡人清單寫成的群發迴圈會超出，所以請分批傳送。

其餘都是一般的 Cloud API 規則。客戶最後一則訊息的 24 小時內，可以傳送自由格式訊息。之後只有已核准的訊息範本能送出，自由格式訊息會回傳錯誤 131047，客戶也不會看到任何內容。

常見錯誤

• 用 JSON 回應輔助函式回傳 challenge。多出的引號會令 Meta 的檢查失敗。
• 先執行 generateText 才回應 Meta。冷啟動時，重試會產生第二則回覆。
• 忘記關閉 MCP 用戶端。每個請求都會留下一個連接，直到平台將其終止。

常見問題

繼續閱讀