whatsapp-messaging

WhatsApp Messaging

使用する場面

Kapso 経由で WhatsApp メッセージを扱うときにこのスキルを使用します。メッセージの送信、テンプレートの作成・管理、メディアのアップロード、受信トレイの履歴の読み取りなどが含まれます。

セットアップ

環境変数：

• KAPSO_API_BASE_URL（ホストのみ。/platform/v1 は含めません）
• KAPSO_API_KEY
• META_GRAPH_VERSION（任意。デフォルトは v24.0）

まず ID を確認する

操作によって、Meta の 2 種類の ID が必要です。

ID	用途	確認方法
business_account_id（WABA）	テンプレートの CRUD	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()

テンプレートのルール

作成時：

• {{param_name}} を使用する parameter_format: "NAMED" を指定します（位置指定より推奨）
• HEADER/BODY で変数を使用する場合は、例を含めます
• language を使用します（language_code ではありません）
• QUICK_REPLY を URL/PHONE_NUMBER ボタンと混在させないでください
• URL ボタンの変数は URL の末尾に置き、位置指定の {{1}} を使用します

送信時：

• NAMED テンプレートでは、ヘッダー／本文のパラメーターに 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 と顧客