integrate-whatsapp

集成 WhatsApp

设置

推荐路径：

已安装并认证 Kapso CLI（kapso login）
在引导或发送消息前，使用 kapso status 确认项目访问权限

备用路径：
环境变量：

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

认证头（直接 API 调用）：

X-API-Key: <api_key>

安装依赖（一次）：

npm i

连接 WhatsApp（设置链接）

推荐引导路径（CLI）：

开始引导：kapso setup
如果设置受阻，通过以下命令解析上下文：
- kapso projects list
- kapso projects use <project-id>
- kapso customers list
- kapso customers new --name "<customer-name>" --external-id <external-id>
- kapso setup --customer <customer-id>
完成托管的引导 URL
确认已连接号码：kapso whatsapp numbers list --output json
解析要操作的确切号码：kapso whatsapp numbers resolve --phone-number "<display-number>" --output json

备用引导流程（直接 API）：

创建客户：POST /platform/v1/customers
生成设置链接：POST /platform/v1/customers/:id/setup_links
客户完成嵌入式注册
使用 phone_number_id 发送消息和配置 Webhook

检测连接：

项目 Webhook whatsapp.phone_number.created（推荐）
成功重定向 URL 查询参数（用于前端用户体验）

推荐的 Kapso 设置链接默认值：

{
  "setup_link": {
    "allowed_connection_types": ["dedicated"],
    "provision_phone_number": true,
    "phone_number_country_isos": ["US"]
  }
}

注意：

kapso setup 和 kapso whatsapp numbers new 默认使用专用号码并自动配置。
将 phone_number_country_isos、phone_number_area_code、language 和重定向 URL 作为可选覆盖项。
平台 API 基础路径：/platform/v1
Meta 代理基础路径：/meta/whatsapp/v24.0（消息、模板、媒体）
使用 phone_number_id 作为主要的 WhatsApp 标识符

接收事件（Webhook）

使用 Webhook 接收：

项目事件（连接生命周期、工作流事件）
电话号码事件（消息、对话、投递状态）

作用域规则：

项目 Webhook：仅项目级事件（连接生命周期、工作流事件）
电话号码 Webhook：仅该 phone_number_id 的 WhatsApp 消息和对话事件
WhatsApp 消息/对话事件（whatsapp.message.*、whatsapp.conversation.*）仅限电话号码

创建 Webhook：

项目级：node scripts/create.js --scope project --url <https://...> --events <csv>
电话号码：node scripts/create.js --phone-number-id <id> --url <https://...> --events <csv>

创建/更新的常用标志：

--url <https://...> - Webhook 目标地址
--events <csv|json-array> - 事件类型（Kapso Webhook）
--kind <kapso|meta> - Kapso（基于事件）与原始 Meta 转发
--payload-version <v1|v2> - 负载格式（推荐 v2）
--buffer-enabled <true|false> - 为 whatsapp.message.received 启用缓冲
--buffer-window-seconds <n> - 1-60 秒
--max-buffer-size <n> - 1-100
--active <true|false> - 启用/禁用

测试投递：

node scripts/test.js --webhook-id <id>

始终验证签名。参见：

references/webhooks-overview.md
references/webhooks-reference.md

发送和读取消息

首先发现 ID

不同操作需要两个 Meta ID：

ID	用途	如何发现
`business_account_id` (WABA)	模板 CRUD	`kapso whatsapp numbers resolve --phone-number "<display-number>" --output json` 或 `node scripts/list-platform-phone-numbers.mjs`
`phone_number_id`	发送消息、上传媒体	`kapso whatsapp numbers resolve --phone-number "<display-number>" --output json` 或 `node scripts/list-platform-phone-numbers.mjs`

首先使用 CLI 操作

常用命令：

kapso whatsapp numbers list --output json
kapso whatsapp numbers resolve --phone-number "<display-number>" --output json
kapso whatsapp messages send --phone-number-id <PHONE_NUMBER_ID> --to <wa-id> --text "Hello from Kapso"
kapso whatsapp messages list --phone-number-id <PHONE_NUMBER_ID> --limit 50 --output json
kapso whatsapp messages get <MESSAGE_ID> --phone-number-id <PHONE_NUMBER_ID> --output json
kapso whatsapp conversations list --phone-number-id <PHONE_NUMBER_ID> --output json
kapso whatsapp templates list --phone-number-id <PHONE_NUMBER_ID> --output json
kapso whatsapp templates get <TEMPLATE_ID> --phone-number-id <PHONE_NUMBER_ID> --output json

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"
});

发送模板消息

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

发送交互式消息

交互式消息需要活跃的 24 小时会话窗口。对于窗口外的出站通知，请使用模板。

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

读取收件箱数据

推荐路径：

CLI：kapso whatsapp messages ...、kapso whatsapp conversations ...、kapso whatsapp templates ...

备用路径：

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

嵌入收件箱

当用户希望将 Kapso 的收件箱放置在自己的应用中时，使用平台 API 收件箱嵌入。

创建：

POST /platform/v1/inbox_embeds
信封：inbox_embed
公共作用域：project、customer、phone_number
scope_id 对于 project 为空，对于 customer 为客户 UUID，对于 phone_number 为 WhatsApp phone_number_id
language 控制嵌入式收件箱 UI 的语言；支持的值有 en 和 es
创建时返回 token 和 embed_url，仅一次。存储 embed_url；列表/获取/更新操作会省略密钥。

示例：

{
  "inbox_embed": {
    "name": "Support inbox",
    "scope_type": "phone_number",
    "scope_id": "1234567890",
    "allowed_origins": ["https://app.example.com"],
    "default_mode": "system",
    "language": "es"
  }
}

管理：

GET /platform/v1/inbox_embeds
GET /platform/v1/inbox_embeds/:id
PATCH /platform/v1/inbox_embeds/:id
DELETE /platform/v1/inbox_embeds/:id（撤销）

模板规则

创建：

使用 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（不能同时使用）

WhatsApp Flows

使用 Flows 构建原生 WhatsApp 表单。在编辑 Flow JSON 之前，请阅读 references/whatsapp-flows-spec.md。

创建和发布 Flow

创建 Flow：node scripts/create-flow.js --phone-number-id <id> --name <name>
更新 JSON：node scripts/update-flow-json.js --flow-id <id> --json-file <path>
发布：node scripts/publish-flow.js --flow-id <id>
测试：node scripts/send-test-flow.js --phone-number-id <id> --flow-id <id> --to <phone>

附加数据端点（动态 Flow）

设置加密：node scripts/setup-encryption.js --flow-id <id>
创建端点：node scripts/set-data-endpoint.js --flow-id <id> --code-file <path>
部署：node scripts/deploy-data-endpoint.js --flow-id <id>
注册：node scripts/register-data-endpoint.js --flow-id <id>

Flow JSON 规则

静态 Flow（无数据端点）：

使用 version: "7.3"
routing_model 和 data_api_version 可选
参见 assets/sample-flow.json

动态 Flow（带数据端点）：

使用 version: "7.3" 和 data_api_version: "3.0"
routing_model 必填（定义有效的屏幕转换）
参见 assets/dynamic-flow.json

数据端点规则

处理函数签名：

async function handler(request, env) {
  const body = await request.json();
  // body.data_exchange.action: INIT | data_exchange | BACK
  // body.data_exchange.screen: 当前屏幕 ID
  // body.data_exchange.data: 用户输入
  return Response.json({
    version: "3.0",
    screen: "NEXT_SCREEN_ID",
    data: { }
  });
}

不要使用 export 或 module.exports
完成时使用 screen: "SUCCESS" 和 extension_message_response.params
不要包含 endpoint_uri 或 data_channel_uri（Kapso 会注入这些）

故障排除

在深入单个资源端点之前，先搜索日志：kapso logs search --query "<wamid-flow-id-request-id-or-endpoint>" --period 7d --source all --limit 20 --output json
预览显示 "flow_token is missing"：Flow 是动态的但没有数据端点。附加一个并刷新。
加密设置错误：在电话号码/WABA 的设置中启用加密。
OAuthException 139000（完整性）：WABA 必须在 Meta 安全中心通过验证。

脚本

Webhook

脚本	用途
`list.js`	列出 Webhook
`get.js`	获取 Webhook 详情
`create.js`	创建 Webhook
`update.js`	更新 Webhook
`delete.js`	删除 Webhook
`test.js`	发送测试事件

消息和模板

脚本	用途	所需 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

Flows

脚本	用途
`list-flows.js`	列出所有 Flow
`create-flow.js`	创建新 Flow
`get-flow.js`	获取 Flow 详情
`read-flow-json.js`	读取 Flow JSON
`update-flow-json.js`	更新 Flow JSON（创建新版本）
`publish-flow.js`	发布 Flow
`get-data-endpoint.js`	获取数据端点配置
`set-data-endpoint.js`	创建/更新数据端点代码
`deploy-data-endpoint.js`	部署数据端点
`register-data-endpoint.js`	向 Meta 注册数据端点
`get-encryption-status.js`	检查加密状态
`setup-encryption.js`	设置 Flow 加密
`send-test-flow.js`	发送测试 Flow 消息
`delete-flow.js`	删除 Flow
`list-flow-responses.js`	列出存储的 Flow 响应
`list-function-logs.js`	列出函数日志
`list-function-invocations.js`	列出函数调用

OpenAPI

脚本	用途
`openapi-explore.mjs`	探索 OpenAPI（搜索/操作/模式/位置）

示例：

node scripts/openapi-explore.mjs --spec whatsapp search "template"
node scripts/openapi-explore.mjs --spec whatsapp op sendMessage
node scripts/openapi-explore.mjs --spec whatsapp schema TemplateMessage
node scripts/openapi-explore.mjs --spec platform ops --tag "WhatsApp Flows"
node scripts/openapi-explore.mjs --spec platform op setupWhatsappFlowEncryption
node scripts/openapi-explore.mjs --spec platform search "setup link"

资源文件

文件	描述
`template-utility-order-status-update.json`	UTILITY 模板，带命名参数和 URL 按钮
`send-template-order-status-update.json`	order_status_update 的发送时负载
`template-utility-named.json`	UTILITY 模板，展示按钮排序规则
`template-marketing-media-header.json`	MARKETING 模板，带 IMAGE 头部
`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`	目录消息
`sample-flow.json`	静态 Flow 示例（无端点）
`dynamic-flow.json`	动态 Flow 示例（带端点）
`webhooks-example.json`	Webhook 创建/更新负载示例

参考资料

references/getting-started.md - 平台入门
references/platform-api-reference.md - 完整端点参考
references/setup-links.md - 设置链接配置
references/detecting-whatsapp-connection.md - 连接检测方法
references/webhooks-overview.md - Webhook 类型、签名验证、重试
references/webhooks-event-types.md - 可用事件
references/webhooks-reference.md - Webhook API 和负载说明
references/templates-reference.md - 模板创建规则、组件速查表、发送时组件
references/whatsapp-api-reference.md - 消息和对话的 Meta 代理负载
references/whatsapp-cloud-api-js.md - 发送和读取消息的 SDK 用法
references/whatsapp-flows-spec.md - Flow JSON 规范

你可能还喜欢

debugging-and-error-recovery

77Kbackend-api

指导系统性的根因调试。当测试失败、构建中断、行为不符合预期或遇到任何意外错误时使用。当你需要系统性地查找并修复根本原因而非猜测时使用。

addyosmani

获取

zustand

81Kbackend-api

LobeHub Zustand 存储约定。在编辑 src/store、存储切片、公共/内部动作、调度动作、flattenActions、乐观更新、选择器、映射或类动作迁移时使用。

lobehub

获取

telegram-bot-builder

44Kbackend-api

构建解决实际问题的Telegram机器人的专家——从简单自动化到复杂的AI驱动机器人。涵盖机器人架构、Telegram Bot API、用户体验、变现策略以及将机器人扩展到数千用户。

sickn33

获取

继续探索

上一个相关 Skillanysearch 下一个相关 Skillxurl

浏览 backend-api 热门 Skills 最近更新