alibabacloud-sms-send-short-message

CLI 合规性要点（请先阅读）

以下声明适用于此 Skill 中的所有 aliyun CLI 调用—— 在执行本文档后续介绍的任何发送／查询操作、工作流步骤或功能场景之前，必须遵守这些声明。

预检查：必须使用 Aliyun CLI 3.3.3 或更高版本

[MUST] 验证：aliyun version——版本必须 >= 3.3.3。

• 首次安装或重大升级： /bin/bash -c "$(curl -fsSL --connect-timeout 10 --max-time 120 https://aliyuncli.alicdn.com/setup.sh)"
• 常规更新（CLI >= 3.3.5）： aliyun upgrade——优先使用此内置自更新功能，而不是重新运行安装脚本。
• 完整安装说明请参见 references/cli-installation-guide.md。

预检查：必须更新 Aliyun CLI 插件

[MUST] 运行 aliyun configure set --auto-plugin-install true 以启用自动插件安装。 [MUST] 运行 aliyun plugin update，确保所有现有插件始终保持最新。

---

可观测性（每次 aliyun 命令都必须遵守）

调用任何云 API 之前，请读取此 Skill 根目录下的 references/manifest.json，并仅将其中顶层、非空的字符串 version 用作 {skill-version}。如果文件缺失、无效，或该字段缺失／为空／不是字符串，请停止并报告错误。切勿编造、猜测或复用其他 Skill 的版本。

将版本和会话绑定到当前 Skill 名称及 Skill 根目录。在本次对话中首次调用此 Skill 的云 API 之前，请生成一个全新的随机 32 位小写十六进制会话 ID。在本次对话中，此 Skill 始终复用该会话 ID；每个 Skill 都必须使用不同的会话 ID。切勿复制文档、示例、其他 Skill 或先前对话中的会话 ID，也切勿发送字面值 {session-id} 占位符。切换 Skill 或返回此 Skill 时，请重新读取此 Skill 的 manifest；这两个值都不得跨 Skill 复用。

规则：每条调用云 API 的 aliyun CLI 命令都必须包含 --user-agent 标志。 本地实用程序命令（例如 configure、plugin、version）不支持此标志，应予以排除。

Markdown 示例为简洁起见可以省略此标志。Agent 必须在每次实际执行时追加下方的完整标志，包括运行时生成或扩展的命令；不要在每个示例代码块中重复 UA 模板。

--user-agent "AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message/{session-id} skill-version/{skill-version}"

UA 的整个值必须用双引号括起来，因为其中包含空格。任何 aliyun API 命令都不得跳过、修改或省略此标志。

脚本／Terraform 执行： 内联注入这两个作用域值：

# Python SDK script
SKILL_SESSION_ID={session-id} SKILL_VERSION={skill-version} python3 scripts/deploy.py

# Terraform
TF_VAR_session_id={session-id} TF_VAR_skill_version={skill-version} terraform apply
# provider: configuration_source = "AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message/${var.session_id} skill-version/${var.skill_version}"

脚本和 Terraform 配置必须要求提供这两个值，并构造相同的 UA 产品。 生成的 Terraform provider 必须设置 configuration_source = "AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message/${var.session_id} skill-version/${var.skill_version}"。

包装脚本 scripts/send_sms.sh 要求在其环境中提供这两个值：

SKILL_SESSION_ID={session-id} SKILL_VERSION={skill-version} ./scripts/send_sms.sh send -p "..." -s "..." -t "..."

概述

此 Skill 基于 aliyun CLI，封装了阿里云短信服务（SMS）的端到端能力，提供以下功能：

• 发送短信：验证码、通知或营销短信（SendSms）。
• 批量发送：可为每个电话号码使用不同的签名和模板参数（SendBatchSms）。
• 签名管理：查询审核状态和签名列表。
• 模板管理：查询审核状态和模板列表。
• 发送状态查询：查询短信发送详情和回执。
• 发送统计查询：查询指定日期范围内汇总的发送、成功和失败数量（QuerySendStatistics）。
• 短信资质查询：列出记录（QuerySmsQualificationRecord）并查询单条记录详情（QuerySingleSmsQualification）——参见 references/sms-qualification.md。
• 发送测试短信：对于尚无已审核签名或模板的账号，可向单个电话号码发送内置的测试验证码短信（SendTestVerification）。无需签名或模板，适合在提交签名或模板审核前验证服务。

交互式参数确认（必读）

执行任何发送类操作（send-sms / send-batch-sms）前，此 Skill 必须先收集以下关键参数：--sign-name、--template-code、--template-param（模板包含占位符时），以及 --phone-numbers / --phone-number-json。

IMPORTANT：参数确认 — 执行任何命令或 API 调用前，必须与用户确认所有可由用户自定义的参数（例如 RegionId、签名/模板名称、电话号码、模板变量等）。未经用户明确同意，不得假设或使用默认值。

处理规则

如果用户没有明确提供签名或模板，AI Agent 不得猜测或捏造。而应：

1. 主动询问用户：“您想使用哪个签名/模板？如果不确定，我可以列出您账号中已审核通过的选项，供您选择。”
2. 用户同意后，调用列表 API：
   • aliyun dysmsapi query-sms-sign-list ...，然后针对每个候选项调用 aliyun dysmsapi get-sms-sign --sign-name <name>。
   • aliyun dysmsapi query-sms-template-list ...
   • 严格筛选：仅保留 SignStatus = 1（已审核通过）的签名和 TemplateStatus = 1 的模板。不得仅因运营商注册情况而排除签名——未注册的运营商仍可能成功发送。应将 SignIspRegisterDetailList[*].RegisterResult（各运营商的注册状态）作为候选表中的额外一列展示，由用户决定。列：索引 / 代码 / 名称 / 内容 / SignStatus / 各运营商注册状态。
3. 确定模板变量：如果所选模板包含 ${xxx} 占位符，应逐一询问每个变量的值，并将其组装为 --template-param JSON。
4. 电话号码：始终要求用户明确提供电话号码；不得将本文档中的占位电话号码（如 13800138000）用作实际收件号码。
5. 最终确认：收集齐所有关键参数后，复述完整的发送计划，并且只有在用户明确确认（例如“确认”/“发送”）后，才调用 send-sms / send-batch-sms。

签名/模板无效时的快速恢复

如果 send-sms 返回 isv.SMS_SIGN_NAME_ILLEGAL / isv.SMS_TEMPLATE_ILLEGAL，Agent 应主动提出“列出已有签名和模板”，并在用户同意后调用列表 API，而不是盲目重试。

账号没有签名或模板时（测试验证）

当用户要求发送短信，但账号既没有已审核通过的签名，也没有已审核通过的模板（例如新账号，或 query-sms-sign-list / query-sms-template-list 未返回任何已审核通过的条目）时，Agent 不得尝试调用 send-sms / send-batch-sms（这些调用会因 isv.SMS_SIGN_NAME_ILLEGAL / isv.SMS_TEMPLATE_ILLEGAL 而失败）。此时应：

1. 说明情况：发送普通短信需要已审核通过的签名和模板，而账号目前还没有。
2. 提供内置测试短信选项：建议使用 send-test-verification，该工具使用阿里云内置的测试签名和模板，只需要一个电话号码。
3. 询问电话号码：请用户输入接收方 --phone（单个号码）。切勿将本文档中的占位符 13800138000 当作实际接收号码重复使用。
4. 确认并发送：用户提供号码并确认后，调用 aliyun dysmsapi send-test-verification --phone <number> --api-version 2017-05-25。
5. 说明后续步骤：提醒用户在控制台创建签名和模板并获得审核通过，以便之后发送正式短信。

前提条件

1. 安装 aliyun CLI（>= 3.3.3） —— 参见 references/cli-installation-guide.md。

2. 安装 dysmsapi 插件：aliyun plugin install --names dysmsapi。

3. 配置凭证 —— 使用 CLI 默认凭证链（优先级：环境变量 → ~/.aliyun/config.json → ECS RAM 角色 → OIDC Token）。使用 aliyun configure get 验证。

   export ALIBABA_CLOUD_ACCESS_KEY_ID=<your-access-key-id>
   export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your-access-key-secret>
   export ALIBABA_CLOUD_REGION_ID=cn-hangzhou
   

   重要：切勿在代码或命令中硬编码 AK/SK。在 ECS 上使用 RAM 角色；在 K8s 中使用 OIDC。

4. 启用短信服务：在 短信控制台 中创建并审核通过签名和模板。没有这些内容时，只能使用 send-test-verification（测试短信）。

用法

直接调用 aliyun CLI

发送短信（批量发送 / 按接收方发送的不同方式请参见示例）：

aliyun dysmsapi send-sms --api-version 2017-05-25 \
  --phone-numbers "13800138000" --sign-name "AliyunDemo" --template-code "SMS_123456" \
  --template-param '{"code":"123456"}' --read-timeout 3

# Batch send: per-phone signature / template params (<= 100 numbers)
aliyun dysmsapi send-batch-sms --api-version 2017-05-25 \
  --phone-number-json '["13800138000","13900139000"]' --sign-name-json '["SignA","SignB"]' \
  --template-code "SMS_123456" \
  --template-param-json '[{"code":"111111"},{"code":"222222"}]' --read-timeout 3

# Test SMS: no signature/template needed, single phone only
aliyun dysmsapi send-test-verification --api-version 2017-05-25 --phone "13800138000" --read-timeout 3

查询列表 / 状态 / 详情：

# Approved signatures / templates (use to populate user choices)
aliyun dysmsapi query-sms-sign-list      --api-version 2017-05-25 --page-index 1 --page-size 50 --read-timeout 3
aliyun dysmsapi query-sms-template-list  --api-version 2017-05-25 --page-index 1 --page-size 50 --read-timeout 3

# Single signature / template lookup
aliyun dysmsapi get-sms-sign     --api-version 2017-05-25 --sign-name "AliyunDemo"     --read-timeout 3
aliyun dysmsapi get-sms-template --api-version 2017-05-25 --template-code "SMS_123456" --read-timeout 3

# Per-message delivery details (use BizId for precise lookup)
aliyun dysmsapi query-send-details --api-version 2017-05-25 \
  --phone-number "13800138000" --send-date "20260326" \
  --page-size 10 --current-page 1 --read-timeout 3

# Aggregated statistics (--is-globe: 1=domestic, 2=intl/HK-Macao-Taiwan).
# Optional filters: --sign-name "AliyunDemo" --template-type 0
aliyun dysmsapi query-send-statistics --api-version 2017-05-25 --is-globe 1 \
  --start-date "20260301" --end-date "20260326" --page-index 1 --page-size 10 --read-timeout 3

# SMS qualification — list records / single detail by GroupId
aliyun dysmsapi query-sms-qualification-record --api-version 2017-05-25 --page-no 1 --page-size 20 --read-timeout 3
aliyun dysmsapi query-single-sms-qualification --api-version 2017-05-25 --qualification-group-id 10000123 --read-timeout 3

资格审核 API 的完整筛选参数、响应架构和状态枚举映射记录在 references/sms-qualification.md 中。

使用包装脚本

scripts/send_sms.sh 会自动应用 --api-version、--read-timeout 和带版本号的 --user-agent。该脚本要求环境中设置 SKILL_SESSION_ID 和 SKILL_VERSION（参见可观测性）；每个会话导出一次即可：

export SKILL_SESSION_ID={session-id} SKILL_VERSION={skill-version}

# Send (single or comma-separated phones); add --verify to pre-check sign/template
./scripts/send_sms.sh send -p "13800138000" -s "AliyunDemo" -t "SMS_123456" -tp '{"code":"123456"}'

# Send a test verification SMS (no signature/template needed)
./scripts/send_sms.sh send-test -p "13800138000"

# List & inspect
./scripts/send_sms.sh list-signs
./scripts/send_sms.sh list-templates
./scripts/send_sms.sh query-sign     --sign-name "AliyunDemo"
./scripts/send_sms.sh query-template --template-code "SMS_123456"

# Status & statistics (--is-globe / --sign-name / --template-type are optional filters)
./scripts/send_sms.sh query-status     -p "13800138000" --send-date "20260326" --biz-id "xxx^0"
./scripts/send_sms.sh query-statistics --start-date "20260301" --end-date "20260326"

参数

aliyun dysmsapi send-sms

参数	必填	描述
--api-version	是	API 版本，固定为 2017-05-25
--phone-numbers	是	电话号码，以逗号分隔，最多 1000 个
--sign-name	是	短信签名名称
--template-code	是	短信模板代码
--template-param	否	模板变量 JSON，例如 '{"code":"123456"}'
--out-id	否	外部跟踪 ID
--read-timeout	是	读取超时时间（秒），建议值为 3

aliyun dysmsapi send-batch-sms（批量发送）

参数	必填	描述
--api-version	是	API 版本，固定为 2017-05-25
--phone-number-json	是	手机号 JSON 数组，最多 100 个，例如 '["138xxx","139xxx"]'
--sign-name-json	是	签名名称 JSON 数组，数量必须与手机号一致
--template-code	是	模板代码（所有手机号使用相同模板）
--template-param-json	否	模板变量 JSON 数组，数量必须与手机号一致
--sms-up-extend-code-json	否	上行短信扩展码 JSON 数组
--out-id	否	外部跟踪 ID，长度小于 256 个字符
--read-timeout	是	读取超时时间，单位为秒，建议值为 3

SendSms 与 SendBatchSms：send-sms 为最多 1000 个号码共用同一签名和模板；send-batch-sms 允许每个手机号使用不同的签名和模板参数（最多 100 个号码）。

aliyun dysmsapi send-test-verification（测试短信，无需签名或模板）

参数	必填	描述
--api-version	是	API 版本，固定为 2017-05-25
--phone	是	单个收件人手机号，例如 13800138000
--read-timeout	是	读取超时时间，单位为秒，建议值为 3

适用场景：仅适用于尚未获得已审核签名或模板的账号。此工具使用阿里云内置的测试签名和模板，免费发送固定的测试验证码至单个号码。此工具不可替代生产环境中的 send-sms——请创建并获取已审核的签名和模板，以发送实际业务短信。

aliyun dysmsapi query-send-statistics

参数	必填	描述
--api-version	是	API 版本，固定为 2017-05-25
--is-globe	是	范围：1 = 国内；2 = 国际／港澳台
--start-date	是	开始日期，格式为 yyyyMMdd
--end-date	是	结束日期，格式为 yyyyMMdd
--page-index	是	当前页，从 1 开始
--page-size	是	页面大小，1~50
--template-type	否	0=验证码，1=通知，2=营销（企业），3=国际／港澳台（企业），7=数字
--sign-name	否	按签名名称筛选
--read-timeout	是	读取超时时间，单位为秒，建议值为 3

响应：返回 Data.TargetList[]（每项包含 SendDate、TotalCount、RespondedSuccessCount、RespondedFailCount、NoRespondedCount）以及 Data.TotalSize。

包装脚本选项

选项	简写	描述
--phone-numbers	-p	手机号码
--sign-name	-s	签名名称
--template-code	-t	模板代码
--template-param	-tp	模板变量（JSON）
--out-id	-o	外部跟踪 ID
--verify	—	发送前验证签名/模板
--region	-r	地域 ID，默认为 cn-hangzhou
--profile	—	使用指定的 aliyun CLI 配置

输出

发送成功响应

{
  "BizId": "114814474505895421^0",
  "Code": "OK",
  "Message": "OK",
  "RequestId": "4C3D8B1B-B3D8-5673-B724-1F251799CE9A"
}

审批状态参考

值	SignStatus / TemplateStatus	描述
0	Reviewing	暂时无法发送短信
1	Approved	可用于发送
2	Rejected	需要修改后重新提交
10	Cancelled	签名/模板已取消

错误处理

常见业务错误代码

错误代码	描述	建议操作
isv.SMS_SIGNATURE_SCENE_ILLEGAL	签名/模板场景不匹配	确保签名与模板场景一致
isv.SMS_TEMPLATE_ILLEGAL	模板缺失或未获批准	确认模板已获批准
isv.SMS_SIGN_NAME_ILLEGAL	签名缺失或未获批准	确认签名已获批准
isv.MOBILE_NUMBER_ILLEGAL	手机号码格式错误	检查号码格式
isv.AMOUNT_NOT_ENOUGH	账户余额不足	充值短信配额
isv.BUSINESS_LIMIT_CONTROL	触发限流	降低发送速率
SignatureNotFound	未找到签名	在控制台创建签名
TemplateNotFound	未找到模板	在控制台创建模板

query-send-details ErrCode = Alibaba isv.*/isp.*（见上文）+ 运营商回执（DELIVERED、MOBILE_NOT_ON_SERVICE、MOBILE_SEND_LIMIT，……）。完整表格和排查指南：references/sms-error-codes.md。

CLI 配置错误

错误消息	原因	解决方法
InvalidAccessKeyId.NotFound	AccessKey ID 错误	检查 AccessKey ID
SignatureDoesNotMatch	Secret 错误	检查 AccessKey Secret
Forbidden.RAM	权限不足	确认 RAM 用户拥有短信权限

执行流程

1. 预检查：已安装 aliyun CLI（>= 3.3.3）且 dysmsapi 插件可用； 已配置凭证；从 references/manifest.json 读取 {skill-version}，并生成一个新的 {session-id}（参见可观测性）。
2. 验证必需参数（phone-numbers、sign-name、template-code）。 如果缺少签名或模板，请询问用户；征得同意后，调用 query-sms-sign-list / query-sms-template-list 并展示已审核通过的候选项。 如果账户中完全没有已审核通过的签名和模板，不要调用 send-sms；请改为提供测试验证短信（步骤 5a）。
3. [可选，--verify] 验证签名：通过 get-sms-sign 检查，要求 SignStatus=1；同时向用户提供 SignIspRegisterDetailList[*].RegisterResult 作为参考信息（未注册的运营商仍可能成功送达——不要因此阻止发送）。
4. [可选，--verify] 通过 get-sms-template 验证模板状态（TemplateStatus=1）。
5. 发送：使用 aliyun dysmsapi send-sms（如需针对每位收件人个性化发送，则使用 send-batch-sms）。 5a. [无签名/模板] 发送测试短信：当账户没有已审核通过的签名/模板时，请向用户索要单个 --phone，并在确认后调用 aliyun dysmsapi send-test-verification --phone <number>。然后引导用户创建签名/模板并通过审核，以便用于正式发送。
6. 返回结果：Code=OK 仅表示网关已受理——返回 BizId。如需向用户报告最终送达情况，务必调用 query-send-details（场景 3）；切勿将发送响应作为送达证明。

示例

场景 1：发送验证码（或使用相同签名/参数群发）

# 1) Pull approved signatures & templates first (so the user can pick)
aliyun dysmsapi query-sms-sign-list     --api-version 2017-05-25 --page-index 1 --page-size 50 --read-timeout 3
aliyun dysmsapi query-sms-template-list --api-version 2017-05-25 --page-index 1 --page-size 50 --read-timeout 3

# 2) Send (after user confirmation). For bulk, comma-separate up to 1000 numbers in
#    --phone-numbers; all of them share this signature and these template params.
aliyun dysmsapi send-sms --api-version 2017-05-25 \
  --phone-numbers "13800138000" --sign-name "YourSign" --template-code "SMS_xxx" \
  --template-param '{"code":"123456"}' --read-timeout 3

场景 2：针对每位收件人个性化批量发送

aliyun dysmsapi send-batch-sms --api-version 2017-05-25 \
  --phone-number-json '["13800138000","13900139000"]' \
  --sign-name-json    '["BrandA","BrandB"]' \
  --template-code "SMS_xxx" \
  --template-param-json '[{"code":"111111"},{"code":"222222"}]' --read-timeout 3

--phone-number-json、--sign-name-json 和 --template-param-json 的长度必须 相同，并且各项必须一一对应。

场景 3：验证送达情况并汇总统计数据

# Per-message delivery (uses BizId returned by send-sms)
aliyun dysmsapi query-send-details --api-version 2017-05-25 \
  --phone-number "13800138000" --send-date "20260326" --biz-id "xxx^0" \
  --page-size 10 --current-page 1 --read-timeout 3

# Range-based aggregated statistics (1 row per send-day)
aliyun dysmsapi query-send-statistics --api-version 2017-05-25 --is-globe 1 \
  --start-date "20260301" --end-date "20260326" --page-index 1 --page-size 10 --read-timeout 3

send-sms / send-batch-sms 响应仅确认网关已受理（Code=OK + BizId），并不能证明短信已送达。每当用户询问“收到了吗？”/“送达了吗？”，务必调用 query-send-details（使用 BizId 精确查询），并展示 SendStatus（1=处理中，2=失败，3=已送达）和 ErrCode——切勿仅依据发送 API 的响应作答。

场景 4：没有签名/模板时发送测试短信

对于没有任何已审核通过的签名/模板的新账户，请向用户索要一个电话号码，然后发送内置的测试验证短信：

aliyun dysmsapi send-test-verification --api-version 2017-05-25 --phone "13800138000" --read-timeout 3

成功响应会返回 Code=OK / Success=true。之后，引导用户在控制台创建签名和模板并通过审核，以便使用 send-sms 发送实际业务短信。

多环境/多账户

aliyun CLI 支持多个配置文件。凭证优先使用环境变量或 RAM 角色；配置文件仅用于选择地域：

aliyun configure set --profile prod --region cn-hangzhou
aliyun dysmsapi send-sms --profile prod --api-version 2017-05-25 \
  --phone-numbers "13800138000" --sign-name "Sign" --template-code "SMS_xxx" --read-timeout 3

注意事项

1. 插件安装：首次使用需要运行 aliyun plugin install --names dysmsapi。
2. API 版本：直接调用 CLI 时，必须指定 --api-version 2017-05-25。
3. 参数格式：使用 kebab-case（例如 --phone-numbers，而不是 --PhoneNumbers）。
4. 超时：必须指定 --read-timeout 3。发生超时后，先查询送达回执，再决定是否重试。
5. User-Agent：每条 API 命令都必须携带 Observability 部分所述的带版本号的 --user-agent，不得使用硬编码或不含会话信息的值。
6. 幂等性：SendSms/SendBatchSms 不具备幂等性，必须在业务层防止重复发送。
7. 单发与批量发送：验证码优先使用 send-sms；只有在每位收件人需要不同签名或模板参数时（≤ 100），才使用 send-batch-sms。
8. 计费：费用取决于运营商是否送达；API 调用成功但运营商发送失败时不收费。每个用户的 QPS 限制为 5000/s。send-test-verification 免费。
9. 凭证安全：切勿硬编码 AK/SK；始终依赖默认凭证链（环境变量 / ~/.aliyun/config.json / ECS RAM 角色 / OIDC）。
10. 参数确认：切勿猜测签名或模板，务必询问用户；取得同意后，获取 query-sms-sign-list / query-sms-template-list（参见“交互式参数确认”）。
11. 发送结果报告：发送响应仅表示网关已受理，不能证明消息已送达；请使用 query-send-details 确认（场景 3）。

参考资料

• Alibaba Cloud CLI 文档
• 短信服务控制台
• SendSms API 文档
• SendTestVerification API（测试短信，无需签名或模板）
• 发送状态错误码（本地） — query-send-details ErrCode（Alibaba isv.*/isp.* + 运营商回执）；上游：101347 / 101346
• 短信资质查询（本地） — QuerySmsQualificationRecord / QuerySingleSmsQualification