whatsapp-messaging

WhatsApp 消息

适用场景

通过 Kapso 处理 WhatsApp 消息时使用此技能：发送消息、创建／管理模板、上传媒体或读取收件箱历史记录。

设置

环境变量：

• KAPSO_API_BASE_URL（仅主机名，不包含 /platform/v1）
• KAPSO_API_KEY
• META_GRAPH_VERSION（可选，默认为 v24.0）

先查找 ID

不同操作需要使用两个 Meta ID：

ID	用途	查找方式
business_account_id (WABA)	模板的增删改查	node scripts/list-platform-phone-numbers.mjs
phone_number_id	发送消息、上传媒体	node scripts/list-platform-phone-numbers.mjs

SDK 设置

安装：

npm install @kapso/whatsapp-cloud-api

创建客户端：

import { WhatsAppClient } from "@kapso/whatsapp-cloud-api";

const client = new WhatsAppClient({
  baseUrl: "https://api.kapso.ai/meta/whatsapp",
  kapsoApiKey: process.env.KAPSO_API_KEY!
});

操作指南

发送文本消息

通过 SDK：

await client.messages.sendText({
  phoneNumberId: "<PHONE_NUMBER_ID>",
  to: "+15551234567",
  body: "Hello from Kapso"
});

发送模板消息

1. 查找 ID：node scripts/list-platform-phone-numbers.mjs
2. 根据 assets/template-utility-order-status-update.json 起草模板负载
3. 创建：node scripts/create-template.mjs --business-account-id <WABA_ID> --file <payload.json>
4. 检查状态：node scripts/template-status.mjs --business-account-id <WABA_ID> --name <name>
5. 发送：node scripts/send-template.mjs --phone-number-id <ID> --file <send-payload.json>

发送交互式消息

交互式消息需要处于有效的 24 小时会话窗口内。要在窗口外发送外发通知，请使用模板。

1. 查找 phone_number_id
2. 从 assets/send-interactive-*.json 中选择负载
3. 发送：node scripts/send-interactive.mjs --phone-number-id <ID> --file <payload.json>

读取收件箱数据

使用 Meta 代理或 SDK：

• 代理：GET /{phone_number_id}/messages、GET /{phone_number_id}/conversations
• SDK：client.messages.query()、client.conversations.list()

模板规则

创建时：

• 使用 parameter_format: "NAMED" 和 {{param_name}}（优先于位置参数）
• 在 HEADER/BODY 中使用变量时，提供示例
• 使用 language（而非 language_code）
• 不要将 QUICK_REPLY 按钮与 URL/PHONE_NUMBER 按钮交错排列
• URL 按钮变量必须位于 URL 末尾，并使用位置参数 {{1}}

发送时：

• 对于 NAMED 模板，在 header/body 参数中包含 parameter_name
• URL 按钮需要一个带有 sub_type: "url" 和 index 的 button 组件
• 媒体标头使用 id 或 link 其中之一（不能同时使用）

脚本

脚本	用途	所需 ID
list-platform-phone-numbers.mjs	查找 business_account_id + phone_number_id	—
list-connected-numbers.mjs	列出 WABA 电话号码	business_account_id
list-templates.mjs	列出模板（支持筛选）	business_account_id
template-status.mjs	检查单个模板状态	business_account_id
create-template.mjs	创建模板	business_account_id
update-template.mjs	更新现有模板	business_account_id
send-template.mjs	发送模板消息	phone_number_id
send-interactive.mjs	发送交互式消息	phone_number_id
upload-media.mjs	上传供发送时标头使用的媒体	phone_number_id

资源文件

文件	说明
template-utility-order-status-update.json	带命名参数和 URL 按钮的 UTILITY 模板
send-template-order-status-update.json	用于发送 order_status_update 的负载
template-utility-named.json	展示按钮排序规则的 UTILITY 模板
template-marketing-media-header.json	带 IMAGE 标头的 MARKETING 模板
template-authentication-otp.json	AUTHENTICATION OTP 模板（COPY_CODE）
send-interactive-buttons.json	交互式按钮消息
send-interactive-list.json	交互式列表消息
send-interactive-cta-url.json	交互式 CTA URL 消息
send-interactive-location-request.json	位置请求消息
send-interactive-catalog-message.json	目录消息

参考资料

• references/templates-reference.md - 模板创建规则、组件速查表、发送时组件
• references/whatsapp-api-reference.md - 消息和对话的 Meta 代理载荷
• references/whatsapp-cloud-api-js.md - 发送和读取消息的 SDK 用法

相关技能

• kapso-automation - 工作流自动化
• whatsapp-flows - WhatsApp Flows
• kapso-api - 平台 API 和客户