alibabacloud-chatapp-message-send

概述

此技能通过 aliyun CLI 封装阿里云 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 — 执行 Agent Skill 必须启用 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 仅用于 Agent Skill 调用场景，技能停止运行后不得继续保持启用状态。

aliyun configure ai-mode disable

2. 安装 cams 插件

aliyun plugin install --names aliyun-cli-cams

3. 验证凭证

预检查：需要阿里云凭证

安全规则：

• 绝不读取、回显或打印 AK/SK 值
• 绝不要求用户在对话或命令行中直接输入 AK/SK
• 绝不使用 aliyun configure set 配置明文凭证值
• 仅使用 aliyun configure list 检查凭证状态

aliyun configure list

检查输出中是否存在有效的配置（AK、STS 或 OAuth 身份）。

如果没有有效配置，请在此处停止。

1. 从阿里云控制台获取凭证
2. 在本会话之外配置凭证（在终端中运行 aliyun configure，或在 shell 配置文件中设置环境变量）
3. 返回并重新运行；确认 aliyun configure list 显示有效配置

4. 启用 Chat App Message Service

在阿里云控制台完成以下操作：

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 字符串；格式因消息类型而异：

• 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：根据消息类型构造 Content 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 权限。请参阅 references/ram-policies.md，了解完整的权限列表和最低权限策略 JSON。

[MUST] 权限失败处理： 执行过程中，任何命令或 API 调用因权限错误而失败时，请按以下流程处理：

1. 阅读 references/ram-policies.md，获取此 SKILL 所需的完整权限列表
2. 使用 ram-permission-diagnose 技能，引导用户申请所需权限
3. 暂停操作，等待用户确认已授予所需权限

注意事项

1. 电话号码格式：所有号码都必须是纯数字，包含国家代码，但不带 +。例如：中国 8613867404376，美国 14155551234。传入 +8613867404376 会引发 InvalidParameter.FromOnlyNumeric
2. 会话时段：只能在用户发送最后一条消息后的 24 小时内发送自定义 WhatsApp 消息。超出此时段必须使用模板消息
3. 模板审批：模板消息必须使用已获批的模板（audit-status = pass）
4. User-Agent：所有 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 消息服务控制台
• SendChatappMessage API 文档
• ListChatappTemplate API 文档
• GetChatappTemplateDetail API 文档