integrate-whatsapp
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseIntegrate WhatsApp
集成WhatsApp
Setup
设置
Env vars:
- (host only, no
KAPSO_API_BASE_URL)/platform/v1 KAPSO_API_KEY- (optional, default
META_GRAPH_VERSION)v24.0
Auth header (direct API calls):
X-API-Key: <api_key>Install deps (once):
bash
npm i环境变量:
- (仅主机地址,不包含
KAPSO_API_BASE_URL)/platform/v1 KAPSO_API_KEY- (可选,默认值为
META_GRAPH_VERSION)v24.0
认证请求头(直接调用API时使用):
X-API-Key: <api_key>安装依赖(仅需执行一次):
bash
npm iConnect WhatsApp (setup links)
连接WhatsApp(设置链接)
Typical onboarding flow:
- Create customer:
POST /platform/v1/customers - Generate setup link:
POST /platform/v1/customers/:id/setup_links - Customer completes embedded signup
- Use to send messages and configure webhooks
phone_number_id
Detect connection:
- Project webhook (recommended)
whatsapp.phone_number.created - Success redirect URL query params (use for frontend UX)
Provision phone numbers (setup link config):
json
{
"setup_link": {
"provision_phone_number": true,
"phone_number_country_isos": ["US"]
}
}Notes:
- Platform API base:
/platform/v1 - Meta proxy base: (messaging, templates, media)
/meta/whatsapp/v24.0 - Use as the primary WhatsApp identifier
phone_number_id
典型的客户入驻流程:
- 创建客户:
POST /platform/v1/customers - 生成设置链接:
POST /platform/v1/customers/:id/setup_links - 客户完成嵌入式注册
- 使用发送消息并配置webhooks
phone_number_id
检测连接状态:
- 项目webhook (推荐使用)
whatsapp.phone_number.created - 成功跳转URL的查询参数(用于前端用户体验优化)
预配电话号码(设置链接配置):
json
{
"setup_link": {
"provision_phone_number": true,
"phone_number_country_isos": ["US"]
}
}注意事项:
- 平台API基础路径:
/platform/v1 - Meta代理基础路径:(用于消息、模板、媒体相关操作)
/meta/whatsapp/v24.0 - 使用作为WhatsApp的主要标识
phone_number_id
Receive events (webhooks)
接收事件(webhooks)
Use webhooks to receive:
- Project events (connection lifecycle, workflow events)
- Phone-number events (messages, conversations, delivery status)
Scope rules:
- Project webhooks: only project-level events (connection lifecycle, workflow events)
- Phone-number webhooks: only WhatsApp message + conversation events for that
phone_number_id - WhatsApp message/conversation events (,
whatsapp.message.*) are phone-number onlywhatsapp.conversation.*
Create a webhook:
- Project-level:
node scripts/create.js --scope project --url <https://...> --events <csv> - Phone-number:
node scripts/create.js --phone-number-id <id> --url <https://...> --events <csv>
Common flags for create/update:
- - webhook destination
--url <https://...> - - event types (Kapso webhooks)
--events <csv|json-array> - - Kapso (event-based) vs raw Meta forwarding
--kind <kapso|meta> - - payload format (
--payload-version <v1|v2>recommended)v2 - - enable buffering for
--buffer-enabled <true|false>whatsapp.message.received - - 1-60 seconds
--buffer-window-seconds <n> - - 1-100
--max-buffer-size <n> - - enable/disable
--active <true|false>
Test delivery:
bash
node scripts/test.js --webhook-id <id>Always verify signatures. See:
references/webhooks-overview.mdreferences/webhooks-reference.md
通过webhooks可接收以下事件:
- 项目事件(连接生命周期、工作流事件)
- 电话号码相关事件(消息、对话、送达状态)
范围规则:
- 项目webhooks:仅接收项目级事件(连接生命周期、工作流事件)
- 电话号码webhooks:仅接收该对应的WhatsApp消息和对话事件
phone_number_id - WhatsApp消息/对话事件(、
whatsapp.message.*)仅支持通过电话号码webhooks接收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>
创建/更新时的常用参数:
- - webhook目标地址
--url <https://...> - - 事件类型(Kapso webhooks)
--events <csv|json-array> - - Kapso(基于事件)或原生Meta转发
--kind <kapso|meta> - - 负载格式(推荐使用
--payload-version <v1|v2>)v2 - - 启用
--buffer-enabled <true|false>事件的缓冲功能whatsapp.message.received - - 缓冲窗口时长,1-60秒
--buffer-window-seconds <n> - - 最大缓冲数量,1-100
--max-buffer-size <n> - - 启用/禁用webhook
--active <true|false>
测试事件送达:
bash
node scripts/test.js --webhook-id <id>请始终验证签名,详情参考:
references/webhooks-overview.mdreferences/webhooks-reference.md
Send and read messages
发送与读取消息
Discover IDs first
先获取所需ID
Two Meta IDs are needed for different operations:
| ID | Used for | How to discover |
|---|---|---|
| Template CRUD | |
| Sending messages, media upload | |
不同操作需要两个Meta ID:
| ID | 用途 | 获取方式 |
|---|---|---|
| 模板的增删改查 | |
| 发送消息、上传媒体 | |
SDK setup
SDK设置
Install:
bash
npm install @kapso/whatsapp-cloud-apiCreate client:
ts
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:
bash
npm install @kapso/whatsapp-cloud-api创建客户端:
ts
import { WhatsAppClient } from "@kapso/whatsapp-cloud-api";
const client = new WhatsAppClient({
baseUrl: "https://api.kapso.ai/meta/whatsapp",
kapsoApiKey: process.env.KAPSO_API_KEY!
});Send a text message
发送文本消息
Via SDK:
ts
await client.messages.sendText({
phoneNumberId: "<PHONE_NUMBER_ID>",
to: "+15551234567",
body: "Hello from Kapso"
});通过SDK发送:
ts
await client.messages.sendText({
phoneNumberId: "<PHONE_NUMBER_ID>",
to: "+15551234567",
body: "Hello from Kapso"
});Send a template message
发送模板消息
- Discover IDs:
node scripts/list-platform-phone-numbers.mjs - Draft template payload from
assets/template-utility-order-status-update.json - Create:
node scripts/create-template.mjs --business-account-id <WABA_ID> --file <payload.json> - Check status:
node scripts/template-status.mjs --business-account-id <WABA_ID> --name <name> - Send:
node scripts/send-template.mjs --phone-number-id <ID> --file <send-payload.json>
- 获取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>
Send an interactive message
发送交互式消息
Interactive messages require an active 24-hour session window. For outbound notifications outside the window, use templates.
- Discover
phone_number_id - Pick payload from
assets/send-interactive-*.json - Send:
node scripts/send-interactive.mjs --phone-number-id <ID> --file <payload.json>
交互式消息需要在24小时会话窗口内发送。如果是窗口外的主动通知,请使用模板消息。
- 获取
phone_number_id - 从中选择对应的负载
assets/send-interactive-*.json - 发送消息:
node scripts/send-interactive.mjs --phone-number-id <ID> --file <payload.json>
Read inbox data
读取收件箱数据
Use Meta proxy or SDK:
- Proxy: ,
GET /{phone_number_id}/messagesGET /{phone_number_id}/conversations - SDK: ,
client.messages.query()client.conversations.list()
可通过Meta代理或SDK读取:
- 代理方式:、
GET /{phone_number_id}/messagesGET /{phone_number_id}/conversations - SDK方式:、
client.messages.query()client.conversations.list()
Template rules
模板规则
Creation:
- Use with
parameter_format: "NAMED"(preferred over positional){{param_name}} - Include examples when using variables in HEADER/BODY
- Use (not
language)language_code - Don't interleave QUICK_REPLY with URL/PHONE_NUMBER buttons
- URL button variables must be at the end of the URL and use positional
{{1}}
Send-time:
- For NAMED templates, include in header/body params
parameter_name - URL buttons need a component with
buttonandsub_type: "url"index - Media headers use either or
id(never both)link
创建模板:
- 推荐使用,参数格式为
parameter_format: "NAMED"(优于位置参数){{param_name}} - 当在标题/正文中使用变量时,请包含示例
- 使用字段(而非
language)language_code - 不要将QUICK_REPLY与URL/PHONE_NUMBER按钮混合使用
- URL按钮的变量必须位于URL末尾,且使用位置参数
{{1}}
发送模板消息:
- 对于NAMED类型的模板,需在标题/正文参数中包含
parameter_name - URL按钮需要包含组件,其中
button并指定sub_type: "url"index - 媒体标题只能使用或
id中的一个(不能同时使用)link
WhatsApp Flows
WhatsApp Flows
Use Flows to build native WhatsApp forms. Read before editing Flow JSON.
references/whatsapp-flows-spec.md使用Flows构建原生WhatsApp表单。在编辑Flow JSON前,请先阅读。
references/whatsapp-flows-spec.mdCreate and publish a flow
创建并发布Flow
- Create flow:
node scripts/create-flow.js --phone-number-id <id> --name <name> - Update JSON:
node scripts/update-flow-json.js --flow-id <id> --json-file <path> - Publish:
node scripts/publish-flow.js --flow-id <id> - Test:
node scripts/send-test-flow.js --phone-number-id <id> --flow-id <id> --to <phone>
- 创建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> - 发布Flow:
node scripts/publish-flow.js --flow-id <id> - 测试Flow:
node scripts/send-test-flow.js --phone-number-id <id> --flow-id <id> --to <phone>
Attach a data endpoint (dynamic flows)
附加数据端点(动态Flow)
- Set up encryption:
node scripts/setup-encryption.js --flow-id <id> - Create endpoint:
node scripts/set-data-endpoint.js --flow-id <id> --code-file <path> - Deploy:
node scripts/deploy-data-endpoint.js --flow-id <id> - Register:
node scripts/register-data-endpoint.js --flow-id <id>
- 设置加密:
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 rules
Flow JSON规则
Static flows (no data endpoint):
- Use
version: "7.3" - and
routing_modelare optionaldata_api_version - See
assets/sample-flow.json
Dynamic flows (with data endpoint):
- Use with
version: "7.3"data_api_version: "3.0" - is required (defines valid screen transitions)
routing_model - See
assets/dynamic-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
Data endpoint rules
数据端点规则
Handler signature:
js
async function handler(request, env) {
const body = await request.json();
// body.data_exchange.action: INIT | data_exchange | BACK
// body.data_exchange.screen: current screen id
// body.data_exchange.data: user inputs
return Response.json({
version: "3.0",
screen: "NEXT_SCREEN_ID",
data: { }
});
}- Do not use or
exportmodule.exports - Completion uses with
screen: "SUCCESS"extension_message_response.params - Do not include or
endpoint_uri(Kapso injects these)data_channel_uri
处理器签名:
js
async function handler(request, env) {
const body = await request.json();
// body.data_exchange.action: INIT | data_exchange | BACK
// body.data_exchange.screen: current screen id
// body.data_exchange.data: user inputs
return Response.json({
version: "3.0",
screen: "NEXT_SCREEN_ID",
data: { }
});
}- 不要使用或
exportmodule.exports - 完成流程时使用,并搭配
screen: "SUCCESS"extension_message_response.params - 不要包含或
endpoint_uri(Kapso会自动注入这些参数)data_channel_uri
Troubleshooting
故障排除
- Preview shows : flow is dynamic without a data endpoint. Attach one and refresh.
"flow_token is missing" - Encryption setup errors: enable encryption in Settings for the phone number/WABA.
- OAuthException 139000 (Integrity): WABA must be verified in Meta security center.
- 预览时显示:动态Flow未附加数据端点,请添加后刷新页面
"flow_token is missing" - 加密设置错误:在电话号码/WABA的设置中启用加密功能
- OAuthException 139000(完整性):WABA必须在Meta安全中心完成验证
Scripts
脚本
Webhooks
Webhooks相关
| Script | Purpose |
|---|---|
| List webhooks |
| Get webhook details |
| Create a webhook |
| Update a webhook |
| Delete a webhook |
| Send a test event |
| 脚本 | 用途 |
|---|---|
| 列出所有webhooks |
| 获取webhook详情 |
| 创建webhook |
| 更新webhook |
| 删除webhook |
| 发送测试事件 |
Messaging and templates
消息与模板相关
| Script | Purpose | Required ID |
|---|---|---|
| Discover business_account_id + phone_number_id | — |
| List WABA phone numbers | business_account_id |
| List templates (with filters) | business_account_id |
| Check single template status | business_account_id |
| Create a template | business_account_id |
| Update existing template | business_account_id |
| Send template message | phone_number_id |
| Send interactive message | phone_number_id |
| Upload media for send-time headers | phone_number_id |
| 脚本 | 用途 | 必填ID |
|---|---|---|
| 获取business_account_id和phone_number_id | — |
| 列出WABA下的电话号码 | business_account_id |
| 列出模板(支持筛选) | business_account_id |
| 检查单个模板的状态 | business_account_id |
| 创建模板 | business_account_id |
| 更新现有模板 | business_account_id |
| 发送模板消息 | phone_number_id |
| 发送交互式消息 | phone_number_id |
| 上传用于消息标题的媒体文件 | phone_number_id |
Flows
Flows相关
| Script | Purpose |
|---|---|
| List all flows |
| Create a new flow |
| Get flow details |
| Read flow JSON |
| Update flow JSON (creates new version) |
| Publish a flow |
| Get data endpoint config |
| Create/update data endpoint code |
| Deploy data endpoint |
| Register data endpoint with Meta |
| Check encryption status |
| Set up flow encryption |
| Send a test flow message |
| Delete a flow |
| List stored flow responses |
| List function logs |
| List function invocations |
| 脚本 | 用途 |
|---|---|
| 列出所有Flow |
| 创建新Flow |
| 获取Flow详情 |
| 读取Flow的JSON配置 |
| 更新Flow的JSON配置(创建新版本) |
| 发布Flow |
| 获取数据端点配置 |
| 创建/更新数据端点代码 |
| 部署数据端点 |
| 在Meta注册数据端点 |
| 检查加密状态 |
| 设置Flow加密 |
| 发送测试Flow消息 |
| 删除Flow |
| 列出已存储的Flow响应 |
| 列出函数日志 |
| 列出函数调用记录 |
OpenAPI
OpenAPI相关
| Script | Purpose |
|---|---|
| Explore OpenAPI (search/op/schema/where) |
Examples:
bash
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"| 脚本 | 用途 |
|---|---|
| 探索OpenAPI(搜索/操作/架构/筛选) |
示例:
bash
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"Assets
资源文件
| File | Description |
|---|---|
| UTILITY template with named params + URL button |
| Send-time payload for order_status_update |
| UTILITY template showing button ordering rules |
| MARKETING template with IMAGE header |
| AUTHENTICATION OTP template (COPY_CODE) |
| Interactive button message |
| Interactive list message |
| Interactive CTA URL message |
| Location request message |
| Catalog message |
| Static flow example (no endpoint) |
| Dynamic flow example (with endpoint) |
| Webhook create/update payload example |
| 文件 | 描述 |
|---|---|
| 带命名参数和URL按钮的UTILITY类型模板 |
| order_status_update模板的发送负载 |
| 展示按钮排序规则的UTILITY类型模板 |
| 带图片标题的MARKETING类型模板 |
| 带COPY_CODE的AUTHENTICATION类型OTP模板 |
| 交互式按钮消息负载 |
| 交互式列表消息负载 |
| 交互式CTA URL消息负载 |
| 位置请求消息负载 |
| 商品目录消息负载 |
| 静态Flow示例 |
| 动态Flow示例 |
| Webhook创建/更新负载示例 |
References
参考文档
- references/getting-started.md - Platform onboarding
- references/platform-api-reference.md - Full endpoint reference
- references/setup-links.md - Setup link configuration
- references/detecting-whatsapp-connection.md - Connection detection methods
- references/webhooks-overview.md - Webhook types, signature verification, retries
- references/webhooks-event-types.md - Available events
- references/webhooks-reference.md - Webhook API and payload notes
- references/templates-reference.md - Template creation rules, components cheat sheet, send-time components
- references/whatsapp-api-reference.md - Meta proxy payloads for messages and conversations
- references/whatsapp-cloud-api-js.md - SDK usage for sending and reading messages
- references/whatsapp-flows-spec.md - Flow JSON spec
- 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规范
Related skills
相关技能
- - Workflows, agents, and automations
automate-whatsapp - - Debugging, logs, health checks
observe-whatsapp
text
[integrate-whatsapp file map]|root: .
|.:{package.json,SKILL.md}
|assets:{dynamic-flow.json,sample-flow.json,send-interactive-buttons.json,send-interactive-catalog-message.json,send-interactive-cta-url.json,send-interactive-list.json,send-interactive-location-request.json,send-template-order-status-update.json,template-authentication-otp.json,template-marketing-media-header.json,template-utility-named.json,template-utility-order-status-update.json,webhooks-example.json}
|references:{detecting-whatsapp-connection.md,getting-started.md,platform-api-reference.md,setup-links.md,templates-reference.md,webhooks-event-types.md,webhooks-overview.md,webhooks-reference.md,whatsapp-api-reference.md,whatsapp-cloud-api-js.md,whatsapp-flows-spec.md}
|scripts:{create-flow.js,create-function.js,create-template.mjs,create.js,delete-flow.js,delete.js,deploy-data-endpoint.js,deploy-function.js,get-data-endpoint.js,get-encryption-status.js,get-flow.js,get-function.js,get.js,list-connected-numbers.mjs,list-flow-responses.js,list-flows.js,list-function-invocations.js,list-function-logs.js,list-platform-phone-numbers.mjs,list-templates.mjs,list.js,openapi-explore.mjs,publish-flow.js,read-flow-json.js,register-data-endpoint.js,send-interactive.mjs,send-template.mjs,send-test-flow.js,set-data-endpoint.js,setup-encryption.js,submit-template.mjs,template-status.mjs,test.js,update-flow-json.js,update-function.js,update-template.mjs,update.js,upload-media.mjs,upload-template-header-handle.mjs}
|scripts/lib:{args.mjs,cli.js,env.js,env.mjs,http.js,output.js,output.mjs,request.mjs,run.js,whatsapp-flow.js}
|scripts/lib/webhooks:{args.js,kapso-api.js,webhook.js}- - 工作流、Agent、自动化
automate-whatsapp - - 调试、日志、健康检查
observe-whatsapp
text
[integrate-whatsapp file map]|root: .
|.:{package.json,SKILL.md}
|assets:{dynamic-flow.json,sample-flow.json,send-interactive-buttons.json,send-interactive-catalog-message.json,send-interactive-cta-url.json,send-interactive-list.json,send-interactive-location-request.json,send-template-order-status-update.json,template-authentication-otp.json,template-marketing-media-header.json,template-utility-named.json,template-utility-order-status-update.json,webhooks-example.json}
|references:{detecting-whatsapp-connection.md,getting-started.md,platform-api-reference.md,setup-links.md,templates-reference.md,webhooks-event-types.md,webhooks-overview.md,webhooks-reference.md,whatsapp-api-reference.md,whatsapp-cloud-api-js.md,whatsapp-flows-spec.md}
|scripts:{create-flow.js,create-function.js,create-template.mjs,create.js,delete-flow.js,delete.js,deploy-data-endpoint.js,deploy-function.js,get-data-endpoint.js,get-encryption-status.js,get-flow.js,get-function.js,get.js,list-connected-numbers.mjs,list-flow-responses.js,list-flows.js,list-function-invocations.js,list-function-logs.js,list-platform-phone-numbers.mjs,list-templates.mjs,list.js,openapi-explore.mjs,publish-flow.js,read-flow-json.js,register-data-endpoint.js,send-interactive.mjs,send-template.mjs,send-test-flow.js,set-data-endpoint.js,setup-encryption.js,submit-template.mjs,template-status.mjs,test.js,update-flow-json.js,update-function.js,update-template.mjs,update.js,upload-media.mjs,upload-template-header-handle.mjs}
|scripts/lib:{args.mjs,cli.js,env.js,env.mjs,http.js,output.js,output.mjs,request.mjs,run.js,whatsapp-flow.js}
|scripts/lib/webhooks:{args.js,kapso-api.js,webhook.js}