Send short messages (SMS) to specified phone numbers via Alibaba Cloud Short Message Service. Supports verification codes, notification messages, and marketing messages. Use this Skill whenever the user wants to send SMS verification codes, system notifications, order reminders, or marketing campaigns. Supports single send (SendSms, up to 1000 phone numbers sharing the same signature and template parameters) and batch send (SendBatchSms, up to 100 phone numbers, each with its own signature and template parameters). The signature and template approval status can be verified before sending to maximize delivery success rate.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Instruções da origem · Visualização somente leitura
name
alibabacloud-sms-send-short-message
description
Send short messages (SMS) to specified phone numbers via Alibaba Cloud Short Message Service. Supports verification codes, notification messages, and marketing messages. Use this Skill whenever the user wants to send SMS verification codes, system notifications, order reminders, or marketing campaigns. Supports single send (SendSms, up to 1000 phone numbers sharing the same signature and template parameters) and batch send (SendBatchSms, up to 100 phone numbers, each with its own signature and template parameters). The signature and template approval status can be verified before sending to maximize delivery success rate.
The following declarations apply to everyaliyun 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:
[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)
When the user does not explicitly provide the signature or template, the AI
agent must not guess or fabricate them. Instead it should:
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."
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.
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.
Phone numbers: Always require explicit phone numbers from the user; never reuse
placeholder numbers like 13800138000 from this document as the actual recipient.
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 && sudomv 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 varsexport 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.
Fixed to AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message
--read-timeout
Yes
Read timeout in seconds, recommended value 3
aliyun dysmsapi send-batch-sms (batch send)
Parameter
Required
Description
--api-version
Yes
API version, fixed to 2017-05-25
--phone-number-json
Yes
Phone numbers JSON array, up to 100, e.g. '["138xxx","139xxx"]'
--sign-name-json
Yes
Signature names JSON array, must match the phone count
--template-code
Yes
Template code (all phones share the same template)
--template-param-json
No
Template variables JSON array, must match the phone count
--sms-up-extend-code-json
No
Upstream SMS extension codes JSON array
--out-id
No
External tracking ID, less than 256 characters
--user-agent
Yes
Fixed to AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message
--read-timeout
Yes
Read timeout in seconds, recommended value 3
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
Parameter
Required
Description
--api-version
Yes
API version, fixed to 2017-05-25
--is-globe
Yes
Scope: 1 = domestic; 2 = international / HK-Macao-Taiwan
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.
[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).
[Optional, --verify] Verify template status via get-sms-template (TemplateStatus=1).
Send via aliyun dysmsapi send-sms (or send-batch-sms for per-recipient
personalization).
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.
[MUST] Disable AI-Mode at every exit (success / failure / cancellation).
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
Plugin install: First-time use requires aliyun plugin install --names dysmsapi.
API version: When calling the CLI directly, --api-version 2017-05-25 is mandatory.
Parameter format: kebab-case (e.g. --phone-numbers, not --PhoneNumbers).
Timeout: --read-timeout 3 is required. After a timeout, query the delivery
receipt before deciding whether to retry.
User-Agent: --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message
is required so the server can identify the caller.
Idempotency: SendSms/SendBatchSms are NOT idempotent — prevent duplicate sends at
the business layer.
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).
Billing: Billing depends on carrier delivery; API success but carrier failure is
not billed. QPS limit is 5000/s per user.
Credential safety: Never hard-code AK/SK; always rely on the default credential
chain (env vars / ~/.aliyun/config.json / ECS RAM role / OIDC).
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").
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.
