@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 或你自己的数据库:
