Skip to main content
@hitheo/whatsapp 軟件包將 Theo 連接到 WhatsApp Cloud API。客戶向你的 WhatsApp 號碼發送消息後,適配器會將每條消息轉發到 POST /api/v1/completions,再通過 Cloud API 回覆。
Theo 不會託管你的 WhatsApp 號碼或令牌。你在 Meta Business Suite 中擁有 WhatsApp Business 賬戶、持有訪問令牌,並在你自己的基礎設施上部署此適配器;Theo 只處理適配器轉發過來的補全流量。你的客戶是在與你的品牌對話,而不是我們的。

前置條件

  1. 一個 WhatsApp Business API 賬戶(通過 Meta Business Suite)
  2. 一個 Theo API 密鑰(theo_sk_...)
  3. 一個用於接收傳入消息的 Webhook URL
  4. Meta App Secret(用於驗證 Webhook 簽名)

安裝

快速設置

該軟件包導出三個函數:
  • createWhatsAppHandler(config) — 返回一個用於處理 WhatsApp Webhook 負載的異步函數。
  • verifyWebhook(params) — 在 Webhook 註冊期間校驗 Meta 的 GET 挑戰請求。
  • verifySignature(rawBody, headerSig, appSecret) — 對入站 POST 請求進行 HMAC-SHA256 簽名校驗。你必須傳入原始請求正文(字節),而不是重新解析後的 JSON 對象。

工作原理

  1. 客戶發送一條 WhatsApp 消息
  2. Meta 通過帶有 X-Hub-Signature-256 請求頭的 POST 請求發送 Webhook 負載
  3. 你的 HTTP 層通過 verifySignature 校驗簽名
  4. 適配器遍歷消息,將文本和媒體轉發給 Theo(附帶按發送者區分的 conversation_id),並將 Theo 的響應通過 Cloud API 發回
  5. 狀態事件(delivered、read)會被靜默確認——不會產生重複回覆

處理器配置

附件

圖片消息(以及 image/* 類型的文檔)會在適配器內部下載,並以base64 圖片數據的形式轉發給 Theo。適配器會向 Graph API 出示 Meta 訪問令牌以獲取字節數據,但絕不會將帶令牌的 Graph CDN URL 繼續向外傳遞——因此不會有憑據流出你的部署環境。圖片說明文字會作為提示詞文本。 語音和音頻消息默認會被忽略,除非你設置 enableVoice: true。啓用後,適配器會下載該音頻片段,使用 Theo 語音轉文本進行轉寫,並將轉寫內容以文本形式追加到提示詞中。

跨實例的會話持久化

默認的 ConversationStore 是進程內存儲。對於無服務器或多實例部署,請接入 Redis 或你自己的數據庫:
在開發階段使用 theo_sk_test_ 密鑰,以避免產生計費。