alibabacloud-sms-send-short-message

What this skill does

## 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:
```bash
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.
```bash
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`](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)

```bash
# 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

```bash
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.

```bash
# 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](https://dysms.console.aliyun.com/): activate the
service, create an **approved** signature, and create an **approved** template.

## Usage

### Calling aliyun CLI directly

**Send SMS**:
```bash
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)**:
```bash
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**:
```bash
# 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 --re