阿里云短信发送助手

Critical CLI Compliance (Must Read First)

The following declarations apply to every aliyun CLI invocation in this Skill —
they must be honored before any send / query operation, workflow step, or functional
scenario described later in this document.

Pre-check: Aliyun CLI >= 3.3.3 required
> Run aliyun version to verify the version is >= 3.3.3. If not installed or the version
> is too low, run curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash to install or
> update.

Pre-check: Aliyun CLI plugin update required
> [MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin
> installation.
> [MUST] run aliyun plugin update to ensure that any existing plugins on your local
> machine are always up-to-date.

[MUST] Enable AI-Mode — AI-mode is required for Agent Skill execution. Run the
following commands before any CLI invocation:

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

[MUST] Disable AI-Mode at EVERY exit point — Before delivering the final response
for ANY reason, always disable AI-mode first. This applies to ALL exit paths: workflow
success, workflow failure, error/exception, user cancellation, session end, or any other
scenario where no further CLI commands will be executed. AI-mode is only used for Agent
Skill invocation scenarios and MUST NOT remain enabled after the skill stops running.

aliyun configure ai-mode disable

[MUST] CLI User-Agent — Every aliyun CLI command invocation in this Skill must
include the flag:
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message

Overview

This Skill wraps the Alibaba Cloud Short Message Service (SMS) end-to-end on top of the
aliyun CLI, exposing the following capabilities:

• Send SMS: verification codes, notifications, or marketing messages (SendSms).
• Batch send: different signatures / template params per phone number (SendBatchSms).
• Signature management: query approval status and signature lists.
• Template management: query approval status and template lists.
• Send status query: query SMS send details and delivery receipts.
• Send statistics query: aggregated send / success / fail counts in a date range
  (QuerySendStatistics).
• SMS qualification query: list records (QuerySmsQualificationRecord) and
  single-record detail (QuerySingleSmsQualification) — see
  references/sms-qualification.md.

Interactive Parameter Confirmation (Must Read)

Before executing any send-class operation (send-sms / send-batch-sms), this Skill
must collect these critical parameters first:

• --sign-name (signature name)
• --template-code (template code)
• --template-param (template variables, when the template contains placeholders)
• --phone-numbers / --phone-number-json (phone numbers)

Handling Rules

When the user does not explicitly provide the signature or template, the AI
agent must not guess or fabricate them. Instead it should:

1. Ask the user proactively: "Which signature/template should I use? If unsure, I can
   list approved ones from your account for you to pick from."
2. After the user agrees, call list APIs:
   - aliyun dysmsapi query-sms-sign-list ... then aliyun dysmsapi get-sms-sign --sign-name <name> per candidate.
   - aliyun dysmsapi query-sms-template-list ...
   - Hard filter: keep only signs with SignStatus = 1 (approved) and templates with TemplateStatus = 1. Do NOT drop signs based on carrier registration alone — unregistered carriers may still deliver. Instead, surface SignIspRegisterDetailList[*].RegisterResult (per-carrier registration status) as an extra column in the candidate table and let the user decide. Columns: index / code / name / content / SignStatus / per-carrier registration.
3. Resolve template variables: If the picked template contains ${xxx} placeholders,
   ask for each variable's value one by one and assemble them into --template-param JSON.
4. Phone numbers: Always require explicit phone numbers from the user; never reuse
   placeholder numbers like 13800138000 from this document as the actual recipient.
5. Final confirmation: Once all critical parameters are collected, restate the
   complete send plan and only call send-sms / send-batch-sms after the user gives an
   explicit confirmation (e.g. "confirm" / "send").

Quick Recovery When Signature / Template Is Invalid

If send-sms returns isv.SMS_SIGN_NAME_ILLEGAL / isv.SMS_TEMPLATE_ILLEGAL, the agent
should proactively offer to "list existing signatures and templates" and, after the user
agrees, call the list APIs instead of retrying blindly.

Prerequisites

1. Install aliyun CLI (>= 3.3.3)

# macOS
brew install aliyun-cli

# Linux
wget https://aliyuncli.alicdn.com/aliyun-cli-linux-latest-amd64.tgz
tar -xzf aliyun-cli-linux-latest-amd64.tgz && sudo mv aliyun /usr/local/bin/

aliyun version  # must be >= 3.3.3

2. Install the dysmsapi plugin

aliyun plugin install --names dysmsapi

3. Configure Credentials

The aliyun CLI default credential chain is recommended; it picks credentials in this
priority order: env vars → ~/.aliyun/config.json → ECS RAM role → OIDC Token.

# Recommended for CI/CD: env vars
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

# Verify
aliyun configure get

> Important: Never hard-code AK/SK in code or commands. Always rely on the default
> credential chain. On ECS use a RAM role; in K8s use OIDC.

4. Activate the SMS Service

In the Alibaba Cloud SMS Console: activate the
service, create an approved signature, and create an approved template.

Usage

Calling aliyun CLI directly

Send SMS:

aliyun dysmsapi send-sms \
  --api-version 2017-05-25 \
  --phone-numbers "13800138000" \
  --sign-name "AliyunDemo" \
  --template-code "SMS_123456" \
  --template-param '{"code":"123456"}' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message \
  --read-timeout 3

Batch send (different signatures / template params):

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"}]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message \
  --read-timeout 3

Query lists / status / details:

# 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 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message --read-timeout 3
aliyun dysmsapi query-sms-template-list  --api-version 2017-05-25 --page-index 1 --page-size 50 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message --read-timeout 3

# Single signature / template lookup
aliyun dysmsapi get-sms-sign     --api-version 2017-05-25 --sign-name "AliyunDemo"     --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message --read-timeout 3
aliyun dysmsapi get-sms-template --api-version 2017-05-25 --template-code "SMS_123456" --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message --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 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message --read-timeout 3

# Aggregated statistics (--is-globe: 1=domestic, 2=intl/HK-Macao-Taiwan)
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 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message --read-timeout 3

# Filter by signature name + template type (optional)
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 \
  --sign-name "AliyunDemo" --template-type 0 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message --read-timeout 3

# SMS qualification — list records (full detail in references/sms-qualification.md)
aliyun dysmsapi query-sms-qualification-record \
  --api-version 2017-05-25 --page-no 1 --page-size 20 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message --read-timeout 3

# SMS qualification — single detail by GroupId
aliyun dysmsapi query-single-sms-qualification \
  --api-version 2017-05-25 --qualification-group-id 10000123 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message --read-timeout 3

> Full filter parameters, response schemas, and state enum mapping for the
> qualification APIs are documented in
> references/sms-qualification.md.

Using the wrapper script

scripts/send_sms.sh automatically applies --api-version, the compliant --user-agent,
and --read-timeout:

# Send (single or comma-separated phones)
./scripts/send_sms.sh send -p "13800138000" -s "AliyunDemo" -t "SMS_123456" -tp '{"code":"123456"}'

# Send with signature/template pre-verification (recommended)
./scripts/send_sms.sh send -p "13800138000" -s "AliyunDemo" -t "SMS_123456" -tp '{"code":"123456"}' --verify

# 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
./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"
./scripts/send_sms.sh query-statistics --start-date "20260301" --end-date "20260326" --is-globe 2

# Filter by signature name and/or template type
./scripts/send_sms.sh query-statistics --start-date "20260301" --end-date "20260326" --sign-name "AliyunDemo" --template-type 0

Parameters

aliyun dysmsapi send-sms

aliyun dysmsapi send-batch-sms (batch send)

> SendSms vs SendBatchSms: send-sms shares one signature/template across up to 1000
> numbers; send-batch-sms lets each phone use a different signature/template params (up
> to 100 numbers).

aliyun dysmsapi query-send-statistics

> Response: returns Data.TargetList[] (each entry has SendDate, TotalCount,
> RespondedSuccessCount, RespondedFailCount, NoRespondedCount) and Data.TotalSize.

Wrapper script options

Output

Successful send response

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

Approval status reference

Error Handling

Common business error codes

> query-send-details ErrCode = Alibaba isv.*/isp.* (above) + carrier receipts (DELIVERED, MOBILE_NOT_ON_SERVICE, MOBILE_SEND_LIMIT, …). Full table + triage: references/sms-error-codes.md.

CLI configuration errors

Execution Flow

1. Pre-check: aliyun CLI installed (>= 3.3.3) and dysmsapi plugin available;
   AI-Mode enabled; credentials configured.
2. Validate required parameters (phone-numbers, sign-name, template-code).
   If signature or template is missing, ask the user; after consent call
   query-sms-sign-list / query-sms-template-list and present approved candidates.
3. [Optional, --verify] Verify sign via get-sms-sign: require SignStatus=1; also surface SignIspRegisterDetailList[*].RegisterResult to the user as info (unregistered carriers may still deliver — do not block).
4. [Optional, --verify] Verify template status via get-sms-template (TemplateStatus=1).
5. Send via aliyun dysmsapi send-sms (or send-batch-sms for per-recipient
   personalization).
6. Return result: Code=OK only confirms gateway acceptance — return BizId. To report final delivery to the user, always call query-send-details (Scenario 4); never use the send response as proof of delivery.
7. [MUST] Disable AI-Mode at every exit (success / failure / cancellation).

Examples

Scenario 1: Send a verification code

# 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 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message --read-timeout 3
aliyun dysmsapi query-sms-template-list --api-version 2017-05-25 --page-index 1 --page-size 50 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message --read-timeout 3

# 2) Send (after user confirmation)
aliyun dysmsapi send-sms \
  --api-version 2017-05-25 \
  --phone-numbers "13800138000" \
  --sign-name "YourSign" --template-code "SMS_xxx" \
  --template-param '{"code":"123456"}' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message --read-timeout 3

Scenario 2: Bulk-send with same signature & params

aliyun dysmsapi send-sms \
  --api-version 2017-05-25 \
  --phone-numbers "13800138000,13900139000,13700137000" \
  --sign-name "YourSign" --template-code "SMS_xxx" \
  --template-param '{"activity":"Double 11 Sale","discount":"50% OFF"}' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message --read-timeout 3

Scenario 3: Batch send with per-recipient personalization

aliyun dysmsapi send-batch-sms \
  --api-version 2017-05-25 \
  --phone-number-json '["13800138000","13900139000","13700137000"]' \
  --sign-name-json    '["BrandA","BrandB","BrandC"]' \
  --template-code "SMS_xxx" \
  --template-param-json '[{"name":"Alice","code":"111111"},{"name":"Bob","code":"222222"},{"name":"Charlie","code":"333333"}]' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message --read-timeout 3

> Lengths of --phone-number-json, --sign-name-json, and --template-param-json must
> match and correspond one-to-one.

Scenario 4: Verify delivery & aggregate statistics

# 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 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message --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 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message --read-timeout 3

> QuerySendDetails vs QuerySendStatistics: query-send-details returns per-message
> records (delivery time, error code) — useful for troubleshooting. query-send-statistics
> returns aggregated daily counts — useful for trend reporting.

Multi-Environment / Multi-Account

aliyun CLI supports multiple profiles. Prefer env vars or RAM roles:

# Option 1: env vars (recommended)
export ALIBABA_CLOUD_ACCESS_KEY_ID=<your-access-key-id>
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your-access-key-secret>

# Option 2: profiles (region only; credentials still come from env vars or RAM role)
aliyun configure set --profile prod --region cn-hangzhou
aliyun configure set --profile test --region cn-shanghai

aliyun dysmsapi send-sms --profile prod \
  --api-version 2017-05-25 \
  --phone-numbers "13800138000" --sign-name "Sign" --template-code "SMS_xxx" \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message --read-timeout 3

Notes

1. Plugin install: First-time use requires aliyun plugin install --names dysmsapi.
2. API version: When calling the CLI directly, --api-version 2017-05-25 is mandatory.
3. Parameter format: kebab-case (e.g. --phone-numbers, not --PhoneNumbers).
4. Timeout: --read-timeout 3 is required. After a timeout, query the delivery
   receipt before deciding whether to retry.
5. User-Agent: --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message
   is required so the server can identify the caller.
6. Idempotency: SendSms/SendBatchSms are NOT idempotent — prevent duplicate sends at
   the business layer.
7. Single vs batch: Prefer send-sms for verification codes; send-batch-sms is only
   needed when each recipient requires different signature or template params (≤ 100).
8. Billing: Billing depends on carrier delivery; API success but carrier failure is
   not billed. QPS limit is 5000/s per user.
9. Credential safety: Never hard-code AK/SK; always rely on the default credential
   chain (env vars / ~/.aliyun/config.json / ECS RAM role / OIDC).
10. Parameter confirmation: Never guess signature/template — always ask the user, and
    after consent fetch query-sms-sign-list / query-sms-template-list (see
    "Interactive Parameter Confirmation").
11. Send-result reporting: send-sms / send-batch-sms responses only confirm gateway acceptance (Code=OK + BizId); they are NOT proof of delivery. Whenever the user asks "did it arrive?" / "was it delivered?", always call query-send-details (use BizId for precise lookup) and surface SendStatus (1=in-flight, 2=failed, 3=delivered) and ErrCode — never reply based on the send-API response alone.

References

• Alibaba Cloud CLI documentation
• SMS Service console
• SendSms API documentation
• Send-status error codes (local) — query-send-details ErrCode (Alibaba isv.*/isp.* + carrier receipts); upstream: 101347 / 101346
• SMS qualification query (local) — QuerySmsQualificationRecord / QuerySingleSmsQualification