@hitheo/whatsapp 軟件包將 Theo 連接到 WhatsApp Cloud API。客戶向你的 WhatsApp 號碼發送消息後,適配器會將每條消息轉發到 POST /api/v1/completions,再通過 Cloud API 回覆。
Theo 不會託管你的 WhatsApp 號碼或令牌。你在 Meta Business Suite 中擁有 WhatsApp Business 賬戶、持有訪問令牌,並在你自己的基礎設施上部署此適配器;Theo 只處理適配器轉發過來的補全流量。你的客戶是在與你的品牌對話,而不是我們的。
前置條件
- 一個 WhatsApp Business API 賬戶(通過 Meta Business Suite)
- 一個 Theo API 密鑰(
theo_sk_...) - 一個用於接收傳入消息的 Webhook URL
- Meta App Secret(用於驗證 Webhook 簽名)
安裝
快速設置
該軟件包導出三個函數:createWhatsAppHandler(config)— 返回一個用於處理 WhatsApp Webhook 負載的異步函數。verifyWebhook(params)— 在 Webhook 註冊期間校驗 Meta 的 GET 挑戰請求。verifySignature(rawBody, headerSig, appSecret)— 對入站 POST 請求進行 HMAC-SHA256 簽名校驗。你必須傳入原始請求正文(字節),而不是重新解析後的 JSON 對象。
工作原理
- 客戶發送一條 WhatsApp 消息
- Meta 通過帶有
X-Hub-Signature-256請求頭的 POST 請求發送 Webhook 負載 - 你的 HTTP 層通過
verifySignature校驗簽名 - 適配器遍歷消息,將文本和媒體轉發給 Theo(附帶按發送者區分的
conversation_id),並將 Theo 的響應通過 Cloud API 發回 - 狀態事件(
delivered、read)會被靜默確認——不會產生重複回覆
處理器配置
附件
圖片消息(以及image/* 類型的文檔)會在適配器內部下載,並以base64 圖片數據的形式轉發給 Theo。適配器會向 Graph API 出示 Meta 訪問令牌以獲取字節數據,但絕不會將帶令牌的 Graph CDN URL 繼續向外傳遞——因此不會有憑據流出你的部署環境。圖片說明文字會作為提示詞文本。
語音和音頻消息默認會被忽略,除非你設置 enableVoice: true。啓用後,適配器會下載該音頻片段,使用 Theo 語音轉文本進行轉寫,並將轉寫內容以文本形式追加到提示詞中。
跨實例的會話持久化
默認的ConversationStore 是進程內存儲。對於無服務器或多實例部署,請接入 Redis 或你自己的數據庫:
