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_ 密钥,以避免产生计费。