Alibabacloud Sms Send Short Message

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

RAM Policies

This Skill calls the Alibaba Cloud Short Message Service (dysmsapi) OpenAPIs and therefore requires the following RAM permissions.

Required Permissions

Minimum Permission Policy

Send SMS only (least privilege). If you also need batch send, add dysms:SendBatchSms to the Action list:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "dysms:SendSms",
      "Resource": "*"
    }
  ]
}

Full Permission Policy

Send SMS plus query signatures, templates, and send status:

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "dysms:SendSms",
        "dysms:SendBatchSms",
        "dysms:GetSmsSign",
        "dysms:GetSmsTemplate",
        "dysms:QuerySmsSignList",
        "dysms:QuerySmsTemplateList",
        "dysms:QuerySendDetails",
        "dysms:QuerySendStatistics",
        "dysms:QuerySmsQualificationRecord",
        "dysms:QuerySingleSmsQualification"
      ],
      "Resource": "*"
    }
  ]
}

How to Apply

1. Sign in to the RAM console. 2. Create a custom policy and paste the JSON above. 3. Attach the policy to the appropriate RAM user or role.

SMS Send-Status Error Codes

Reference for the per-message ErrorCode field returned by

aliyun dysmsapi query-send-details. Two layers of codes are combined:

>

1. Alibaba platform codes (isv.* / isp.*) — surfaced by Alibaba pre-checks

or the SMS gateway before the message is handed off to the carrier.

2. Carrier receipts (DELIVERED, MOBILE_NOT_ON_SERVICE, …) — async

delivery receipts pushed back by domestic carriers (China Mobile / Unicom /

Telecom). Receipt arrival typically takes 10–30 s; absence is common when

SendStatus = 1 (sent) but not yet SendStatus = 3 (delivered).

>

Upstream source:

Domestic SMS delivery-receipt error codes (101347).

---

How to read query-send-details output

query-send-details returns SmsSendDetailDTOs[], where each entry carries:

Important — empty `ErrCode` semantics:

• SendStatus = 1 + empty ErrCode → in flight, retry the query later (carrier receipt not arrived yet).
• SendStatus = 2 + non-empty ErrCode → failure, look up the code below.
• SendStatus = 3 + ErrCode = DELIVERED (or empty) → success.

---

Section 1 — Alibaba platform codes (isv.* / isp.*)

Returned synchronously at send time and echoed in the receipt. Most can also appear as the response Code of SendSms / SendBatchSms (see SKILL.md Error Handling).

1.1 Account & service-level

1.2 Signature / template / content

1.3 Recipient / quota / control

---

Section 2 — Carrier delivery error codes

Pushed asynchronously by the carrier after the message reaches the destination (or fails to). They populate ErrCode only after SendStatus transitions to 2 (failed) or 3 (delivered).

2.1 Success

2.2 Recipient-side failures

2.3 Content / route-side failures

The carrier code list above is non-exhaustive — carriers may add or rename

codes without notice. Treat unknown values as transient unless they repeat

across many recipients within a short window (then open a ticket).

---

Section 3 — Triage workflow

Use this decision tree when investigating a failed message:

1. Read `SendStatus` first:

• 1 (in flight) → wait 30 s and re-query; do not retry sending yet.
• 3 (delivered) → success path; ignore ErrCode.
• 2 (failed) → continue below.

2. Inspect `ErrCode` prefix:

• isv.* / isp.* → look up Section 1.
• Account / signature / template issues → fix in console; do not

retry the same payload until the root cause clears.

• Throttling (BUSINESS_LIMIT_CONTROL / *_LIMIT_CONTROL) → exponential

back-off retry, or raise the threshold in console.

• Otherwise carrier code → look up Section 2.
• Recipient-side failures → mark recipient invalid; do not retry blindly.
• Content / route-side failures → fix content; resend after re-approval.

3. No `ErrCode` but `SendStatus = 2` is rare and indicates an internal gateway issue — open a ticket with the BizId and RequestId.

4. Aggregate analysis: if a single date's RespondedFailCount is unusually high, run query-send-statistics (per signature) to confirm it is not isolated to one signature/template, then sample 20 failed BizIds via query-send-details to identify the dominant ErrCode.

---

Section 4 — Example: enrich a failed delivery report

# 1) For a known phone + date, list per-message details
aliyun dysmsapi query-send-details \
  --api-version 2017-05-25 \
  --phone-number "13800138000" --send-date "20260326" \
  --page-size 50 --current-page 1 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message --read-timeout 3

Parse SmsSendDetailDTOs[] and group by ErrCode:

from collections import Counter
import json, sys
data = json.load(sys.stdin)["SmsSendDetailDTOs"]["SmsSendDetailDTO"]
codes = Counter((d["SendStatus"], d.get("ErrCode") or "") for d in data)
for k, v in sorted(codes.items(), key=lambda x: -x[1]):
    print(f"status={k[0]} code={k[1]:<35s} count={v}")

Cross-reference each ErrCode against Section 1/2 above to choose the right remediation (fix template, revise audience, raise quota, …).

---

References

• Domestic SMS delivery-receipt error codes (101347)
• SMS service error codes (101346)
• QuerySendDetails API
• Local: `SKILL.md` — ## Error Handling section; RAM action list is referenced from there.

SMS Qualification Query Reference

This document describes the two dysmsapi qualification query APIs supported by this Skill. Both commands MUST honor the global compliance rules declared in SKILL.md → Critical CLI Compliance (Must Read First):

• aliyun CLI ≥ 3.3.3 with up-to-date plugins
• AI-Mode enabled before invocation, disabled at every exit
• --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message on

every CLI invocation

• --read-timeout 3 and --api-version 2017-05-25

---

1. QuerySmsQualificationRecord — List Qualification Records

Query the list of SMS qualification records under the current account, including audit details. Supports both full-list query (no filters) and conditional query.

Use this API to discover the GroupId you need before calling

QuerySingleSmsQualification for the full detail.

CLI command

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

Parameters

Filter examples

# Only approved (PASS) qualifications
aliyun dysmsapi query-sms-qualification-record \
  --api-version 2017-05-25 --state PASS --page-no 1 --page-size 50 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message --read-timeout 3

# By company name + self-use only
aliyun dysmsapi query-sms-qualification-record \
  --api-version 2017-05-25 \
  --company-name "Aliyun Communication Co., Ltd." --use-by-self true \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-sms-send-short-message --read-timeout 3

Response shape (key fields)

{
  "Code": "OK",
  "Message": "OK",
  "RequestId": "25D5AFDE-...",
  "Success": true,
  "Data": {
    "PageNo": 1,
    "PageSize": 20,
    "Total": 25,
    "List": [
      {
        "GroupId": 10000123,
        "QualificationGroupName": "Aliyun Communication Co., Ltd. - LiHua",
        "CompanyName": "Aliyun Communication Co., Ltd.",
        "LegalPersonName": "LiHua",
        "WorkOrderId": 20011234,
        "StateName": "INIT",
        "AuditRemark": "N/A",
        "AuditTime": "2024-12-26 17:29:04",
        "CreateDate": "2025-02-20 11:59:30",
        "UseBySelf": true
      }
    ]
  }
}

StateName enumeration (list API)

If StateName == NOT_PASS, read AuditRemark to find out why and call the

"Modify SMS qualification" API or fix it via the SMS console, then re-submit.

---

2. QuerySingleSmsQualification — Single Qualification Detail

Fetch the full detail (company / legal person / admin contact / business license images / etc.) of one qualification by its GroupId. Use this AFTER you have located the target qualification via QuerySmsQualificationRecord.

CLI command

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

Parameters

Response shape (key fields)

{
  "Code": "OK",
  "Message": "OK",
  "RequestId": "25D5AFDE-...",
  "Success": true,
  "Data": {
    "QualificationGroupId": 10000123,
    "QualificationName": "Aliyun Communication Co., Ltd. - LiHua",
    "CompanyName": "Aliyun Communication Co., Ltd.",
    "CompanyType": "COMPANY",
    "OrganizationCode": "910X********0012",
    "LegalPersonName": "LiHua",
    "LegalPersonIDCardType": "identityCard",
    "LegalPersonIDCardNo": "511391********5123",
    "LegalPersonIdCardEffTime": "2023-01-01~2033-01-01",
    "AdminName": "LiHua",
    "AdminPhoneNo": "137*******",
    "AdminIDCardType": "identityCard",
    "AdminIDCardNo": "511391********5123",
    "AdminIDCardExpDate": "2023-01-01~2033-01-01",
    "AdminIDCardFrontFace": "https://...aliyuncs.com/...",
    "AdminIDCardPic": "https://...aliyuncs.com/...",
    "BusinessType": "dysms",
    "BusinessLicensePics": [
      { "Type": "businessLicense", "LicensePic": "123456/111.png",
        "PicUrl": "https://...aliyuncs.com/..." }
    ],
    "OtherFiles": [
      { "LicensePic": "123456/111.png", "PicUrl": "https://...aliyuncs.com/..." }
    ],
    "EffTimeStr": "2023-01-01~2033-01-01",
    "UseBySelf": false,
    "WhetherShare": false,
    "WorkOrderId": 20011234,
    "State": "PASSED",
    "Remark": "N/A"
  }
}

State enumeration (single-detail API — note the values differ from list)

The single-detail API does NOT return AuditRemark. To get the rejection

reason, fall back to QuerySmsQualificationRecord filtered by

--work-order-id of the same record.

---

Typical workflow

1. Call query-sms-qualification-record (--state PASS) to locate the target
   qualification, take its `GroupId`.
2. Call query-single-sms-qualification --qualification-group-id <GroupId>
   to fetch the full company / legal-person / admin / license detail.
3. If the list API shows StateName == NOT_PASS, read `AuditRemark` and either
   modify the qualification or open the SMS console to re-submit.

Notes

1. Audit windows — qualification audits are processed Mon–Sun 09:00~21:00, typically within 2 working days. Be patient and re-query rather than re-submitting. 2. State naming inconsistency — StateName in the list API and State in the single-detail API use different vocabularies (PASS vs PASSED, INIT vs INT, NOT_PASS vs FAILED, CANCEL vs CANCELED). When correlating results across the two APIs, normalize them at the call-site. 3. PII safety — responses contain ID-card numbers, license images, admin phone numbers. Do NOT log them verbatim or echo them to the user without redaction; mask middle digits when displaying. 4. Pagination — query-sms-qualification-record uses --page-no / --page-size (max 50). Iterate pages until Data.PageNo * Data.PageSize >= Data.Total to walk the full list. 5. RAM permissions — both APIs require the calling RAM identity to hold read permission on dysmsapi. See SKILL.md for the full RAM action list and policy reference.

References

• QuerySmsQualificationRecord docs
• QuerySingleSmsQualification docs