alibabacloud-chatapp-message-send

概要

このスキルは、aliyun CLI を介して Alibaba Cloud Chat App Message Service（CAMS）を利用し、次の主要な機能を提供します。

• テンプレートメッセージの送信：変数を置換して、WhatsApp のテンプレートベースのメッセージを送信します
• カスタムメッセージの送信：24 時間のセッションウィンドウ内で、自由形式のメッセージ（テキスト、画像、動画、音声、ドキュメント、インタラクティブ、位置情報）を送信します
• テンプレートの一覧表示：監査ステータス、種類、言語で絞り込んで、すべてのメッセージテンプレートを照会します
• テンプレート詳細の取得：送信パラメーターを正しく入力できるよう、テンプレートの構造と変数を確認します

前提条件

1. CLI バージョンの確認

事前確認：Aliyun CLI >= 3.3.3 が必要です aliyun version を実行して、バージョンが >= 3.3.3 であることを確認してください。未インストールの場合、またはバージョンが古い場合は、 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash を実行して更新するか、 インストール手順については references/cli-installation-guide.md を参照してください。

事前確認：Aliyun CLI プラグインの更新が必要です [MUST] aliyun configure set --auto-plugin-install true を実行して、自動プラグインインストールを有効にしてください。 [MUST] aliyun plugin update を実行して、既存のプラグインが常に最新の状態になるようにしてください。

[MUST] CLI の User-Agent — aliyun CLI コマンドを実行するたびに、次を含める必要があります。 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-chatapp-message-send

[MUST] AI-Mode を有効化 — エージェントスキルの実行には AI-mode が必要です。 CLI コマンドを実行する前に、次のコマンドを実行してください。

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-chatapp-message-send"

[MUST] すべての終了時に AI-Mode を無効化 — どのような理由であっても、最終応答を返す前に、必ず AI-mode を無効にしてください。これは、ワークフローの成功、ワークフローの失敗、エラー／例外、ユーザーによるキャンセル、セッションの終了、または CLI コマンドをそれ以上実行しないその他の状況を含む、すべての終了経路に適用されます。 AI-mode はエージェントスキルの実行時にのみ使用され、スキルの停止後も有効なままにしてはなりません。

aliyun configure ai-mode disable

2. cams プラグインのインストール

aliyun plugin install --names aliyun-cli-cams

3. 認証情報の確認

事前確認：Alibaba Cloud の認証情報が必要です

セキュリティルール：

• AK／SK の値を読み取ったり、エコーしたり、出力したりすることは絶対にしないでください
• 会話やコマンドラインで AK／SK を直接入力するようユーザーに求めることは絶対にしないでください
• リテラルの認証情報を指定して aliyun configure set を使用することは絶対にしないでください
• 認証情報の状態確認には aliyun configure list のみを使用してください

aliyun configure list

有効なプロファイル（AK、STS、または OAuth ID）があることを出力で確認してください。

有効なプロファイルがない場合は、ここで停止してください。

1. Alibaba Cloud コンソールから認証情報を取得します
2. このセッションの外で認証情報を設定します（ターミナルで aliyun configure を実行するか、シェルプロファイルで環境変数を設定します）
3. aliyun configure list に有効なプロファイルが表示された後、戻って再実行します

4. Chat App Message Service の有効化

Alibaba Cloud コンソールで、次の手順を完了してください。

1. Chat App Message Service を有効にします
2. WhatsApp Business Account（WABA）をバインドします
3. 送信者の電話番号を登録し、承認を取得します（From）
4. メッセージテンプレートを作成し、承認を取得します（テンプレートメッセージに必要）

使用方法

aliyun CLI を直接使用

テンプレートメッセージを送信：

aliyun cams send-chatapp-message \
  --channel-type whatsapp \
  --type template \
  --from "86138xxxx" \
  --to "86139xxxx" \
  --template-code "hello_world" \
  --biz-language "en" \
  --template-params 1=Alice 2=Bob \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-chatapp-message-send

カスタムテキストメッセージを送信：

aliyun cams send-chatapp-message \
  --channel-type whatsapp \
  --type message \
  --from "86138xxxx" \
  --to "86139xxxx" \
  --message-type text \
  --content '{"text":"Hello, this is a test message"}' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-chatapp-message-send

承認済みテンプレートを一覧表示：

aliyun cams list-chatapp-template \
  --audit-status pass \
  --template-type WHATSAPP \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-chatapp-message-send

テンプレート詳細を取得：

aliyun cams get-chatapp-template-detail \
  --template-code "hello_world" \
  --biz-language "en" \
  --template-type WHATSAPP \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-chatapp-message-send

ラッパースクリプトを使用

このスキルには、送信前の確認を含む、簡単に実行できる Python ラッパースクリプトが用意されています。

承認済みテンプレートを一覧表示：

python scripts/list_templates.py --audit-status pass --template-type WHATSAPP

テンプレート詳細を取得（変数の構造を確認）：

python scripts/get_template_detail.py --template-code hello_world --language en

テンプレートメッセージを送信（確認あり）：

python scripts/send_chatapp_message.py send-template \
  --from "86138xxxx" --to "86139xxxx" \
  --template-code hello_world --language en \
  --template-params 1=Alice 2=Bob

カスタムメッセージを送信（確認あり）：

python scripts/send_chatapp_message.py send-message \
  --from "86138xxxx" --to "86139xxxx" \
  --message-type text \
  --content '{"text":"Hello"}'

確認をスキップして直接送信：

python scripts/send_chatapp_message.py send-template ... --yes

コマンドのみをプレビュー（ドライラン）：

python scripts/send_chatapp_message.py send-template ... --dry-run

パラメーターリファレンス

aliyun cams send-chatapp-message のパラメーター

パラメーター	必須	説明
--channel-type	はい	チャネルの種類：whatsapp ／ viber
--type	はい	メッセージの種類：template（テンプレートメッセージ）／ message（カスタムメッセージ）
--from	はい	送信者の電話番号。数字のみで、コンソールに登録され、承認済みである必要があります（例：8613867404376）
--to	はい	国番号を含む受信者の電話番号。数字のみで、+を付けません（例：8619521605234）
--template-code	テンプレートの場合は必須	テンプレートコード
--biz-language	テンプレートの場合は必須	テンプレートの言語。例：en、zh_CN
--template-params	いいえ	key=value形式のテンプレート変数。複数指定する場合はスペースで区切ります
--message-type	カスタムメッセージの場合は必須	コンテンツの種類：text／image／video／audio／document／interactive／locationなど
--content	カスタムメッセージの場合は必須	JSON 文字列形式のメッセージコンテンツ
--cust-space-id	いいえ	ISV アカウントのスペース ID
--user-agent	はい	固定値 AlibabaCloud-Agent-Skills/alibabacloud-chatapp-message-send

カスタムメッセージのコンテンツに使う JSON 形式

--contentパラメーターは JSON 文字列です。形式は message-type によって異なります。

• text：{"text":"Message content"}
• image：{"link":"https://example.com/img.jpg","caption":"Description"}
• video：{"link":"https://example.com/vid.mp4","caption":"Description"}
• audio：{"link":"https://example.com/aud.mp3"}
• document：{"link":"https://example.com/doc.pdf","fileName":"doc.pdf"}
• location：{"latitude":"39.9042","longitude":"116.4074","name":"Tiananmen","address":"Beijing"}
• interactive：{"type":"button","action":{"buttons":[{"type":"reply","reply":{"id":"btn1","title":"Confirm"}}]}}

コアワークフローとパラメーターの確認

IMPORTANT: パラメーターの確認 — コマンドまたは API 呼び出しを実行する前に、 ユーザーがカスタマイズ可能なすべてのパラメーター（例：From、To、テンプレートコード、言語、テンプレートパラメーター、コンテンツ JSON など）を 必ずユーザーに確認してください。ユーザーの明示的な承認なしに、値を推測したり、デフォルト値を使用したりしないでください。

テンプレートメッセージの送信フロー

ステップ 1：送信者と受信者の電話番号を確認する

• 送信者（From）：コンソールに登録されている WhatsApp 番号。+ を付けず、数字のみで指定します（例：8613867404376）。
• 受信者（To）：送信先ユーザーの WhatsApp 番号。国番号を含め、+ を付けず、数字のみで指定します（例：8619521605234）。

ステップ 2：テンプレートコードを選択する

• python scripts/list_templates.py --audit-status pass を実行し、承認済みテンプレートを照会します。
• 一覧からテンプレートコードを選ぶようユーザーに案内します。

ステップ 3：テンプレートの言語を確認する

• テンプレートの言語（例：en、zh_CN、zh_HK）をユーザーに尋ねます。

ステップ 4：テンプレート変数を確認し、入力を案内する

• python scripts/get_template_detail.py --template-code <CODE> --language <LANG> を実行します。
• 出力された変数一覧に基づき、各変数の値を一つずつ入力するようユーザーに案内します。
• 変数の形式：--template-params 1=value1 2=value2 3=value3

ステップ 5：送信前に確認する

• スクリプトがすべてのパラメーターを自動で要約し、ユーザーに表示して確認を求めます。
• ユーザーが yes と入力した後にのみ送信が実行されます。

カスタムメッセージの送信フロー

ステップ 1：送信者と受信者の電話番号を確認する（上記と同じ）

ステップ 2：メッセージの種類を確認する

• メッセージの種類（text／image／video／audio／document／interactive／location）をユーザーに尋ねます。

ステップ 3：メッセージの種類に基づいてコンテンツの JSON を作成する

• 選択した種類に応じて必要なフィールド（例：テキストには text、画像には link が必要です）をユーザーに入力してもらいます。
• JSON 文字列を --content パラメーターとして作成します。

ステップ 4：送信前に確認する

• スクリプトが内容を自動で要約して表示します。ユーザーが yes と入力した後に送信されます。

注：カスタム WhatsApp メッセージを送信できるのは、24 時間のセッションウィンドウ内（ユーザーの最後のメッセージから 24 時間以内）のみです。ウィンドウ外ではテンプレートメッセージを使用する必要があります。

出力リファレンス

送信成功時の応答

{
  "Code": "OK",
  "Message": "OK",
  "RequestId": "4C3D8B1B-B3D8-5673-B724-1F251799CE9A",
  "Data": {
    "MessageId": "wamid.xxx"
  }
}

テンプレート一覧の例

Found 3 templates:

  - hello_world | Welcome Template | Language: en | Status: pass | Category: MARKETING | WHATSAPP
  - otp_verification | OTP | Language: zh_CN | Status: pass | Category: AUTHENTICATION | WHATSAPP

エラー処理

よくあるエラーコード

エラーコード	説明	解決方法
InvalidParameter.FromOnlyNumeric	電話番号に + が含まれています	API では数字のみの形式が必要です。+ を削除してください（例：8613867404376）。
TemplateNotFound	テンプレートが存在しません	テンプレートコードと言語が正しいことを確認してください
TemplateParamInvalid	テンプレート変数のエラー	変数の数と形式がテンプレートに一致していることを確認してください
SessionWindowExpired	セッションウィンドウの期限切れ	カスタムメッセージはユーザーの最後の返信から 24 時間以内に送信する必要があります。代わりにテンプレートメッセージを使用してください
PhoneNumberNotRegistered	送信者が登録されていません	コンソールで電話番号の登録と承認を完了してください
Forbidden.RAM	権限が不足しています	RAM ユーザーに CAMS の権限があるか確認してください

CLI 設定エラー

エラーメッセージ	原因	解決方法
InvalidAccessKeyId.NotFound	AccessKey ID が間違っています	AccessKey ID を確認してください
SignatureDoesNotMatch	Secret が間違っています	AccessKey Secret を確認してください
Forbidden.RAM	権限が不足しています	RAM ユーザーの権限を確認してください

RAM 権限

このスキルでは、CAMS API の RAM 権限が必要です。必要な権限の一覧と最小権限のポリシー JSON については、references/ram-policies.md を参照してください。

[MUST] 権限エラーへの対応： 実行中に権限エラーが原因でコマンドまたは API 呼び出しが失敗した場合は、次の手順に従ってください。

1. references/ram-policies.md を読み、この SKILL に必要な権限の一覧を確認します
2. ram-permission-diagnose スキルを使用して、必要な権限を申請するようユーザーを案内します
3. 必要な権限が付与されたことをユーザーが確認するまで待機します

注意事項

1. 電話番号の形式：すべての番号は、国番号を含め、+ を付けずに数字のみで指定する必要があります。例：中国 8613867404376、米国 14155551234。+8613867404376 を渡すと、InvalidParameter.FromOnlyNumeric エラーが発生します
2. セッションの時間枠：カスタム WhatsApp メッセージは、ユーザーの最後のメッセージから 24 時間以内にのみ送信できます。この時間枠を過ぎた場合は、テンプレートメッセージを使用する必要があります
3. テンプレートの承認：テンプレートメッセージでは、承認済みのテンプレート（audit-status = pass）を使用する必要があります
4. ユーザーエージェント：すべての CLI コマンドに --user-agent AlibabaCloud-Agent-Skills/alibabacloud-chatapp-message-send を含める必要があります
5. 認証情報のセキュリティ：AK/SK をコードやコマンドにハードコードしないでください
6. Viber の制限事項：Viber メッセージではテンプレートは不要ですが、promotion／transaction タイプの制限があります
7. コンテンツ JSON：カスタムメッセージの --content パラメーターには、有効な JSON 文字列を指定する必要があります
8. ISV シナリオ：ISV アカウントを使用する場合は、--cust-space-id も指定してください

関連リソース

• Alibaba Cloud CLI ドキュメント
• Chat App Message Service コンソール
• SendChatappMessage API ドキュメント
• ListChatappTemplate API ドキュメント
• GetChatappTemplateDetail API ドキュメント