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 查詢參數（用於前端 UX）

建議的 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（事件驅動）vs 原始 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": "支援收件匣",
    "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 按鈕需要一個 button 元件，包含 sub_type: "url" 和 index
多媒體標頭使用 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>

附加資料端點（動態 flows）

設定加密：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 (Integrity)：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`	列出所有 flows
`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（search/op/schema/where）

範例：

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

獲取

api-patterns

46Kbackend-api

API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.

sickn33

獲取

networkx

41Kbackend-api

Create, analyze, and visualize complex networks and graphs in Python with NetworkX. Use when working with network/graph data structures, computing graph algorithms (shortest paths, centrality, clustering), detecting communities, generating synthetic networks (random, scale-free, small-world), reading/writing graph file formats, or drawing network topologies. Common applications include social, biological, transportation, and citation networks.

k-dense-ai

獲取

繼續探索

瀏覽 backend-api 熱門 Skills 最近更新