/alibabacloud-sms-send-short-message

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.
license: Apache-2.0
compatibility: >
  aliyun-cli >= 3.3.3
  dysmsapi plugin (auto-installed)
  Requires Alibaba Cloud AccessKey configured via `aliyun configure`
metadata:
  domain: cloud-communication
  owner: sms-team
  contact: sms-team@alibaba-inc.com
  implementation: aliyun-cli
  ram_policies: references/ram-policies.md

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`](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