alibabacloud-chatapp-message-send

What this skill does

## Overview

This skill wraps the Alibaba Cloud Chat App Message Service (CAMS) via **aliyun CLI**, providing the following core capabilities:

- **Send Template Messages**: Send WhatsApp template-based messages with variable substitution
- **Send Custom Messages**: Send free-form messages (text, image, video, audio, document, interactive, location) within the 24-hour session window
- **List Templates**: Query all message templates with filtering by audit status, type, and language
- **Get Template Detail**: View template structure and variables to correctly fill in send parameters

## Prerequisites

### 1. CLI Version Verification

> **Pre-check: Aliyun CLI >= 3.3.3 required**
> Run `aliyun version` to verify >= 3.3.3. If not installed or version too low,
> run `curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash` to update,
> or see `references/cli-installation-guide.md` for installation instructions.
>
> **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 are always up-to-date.

**[MUST] CLI User-Agent** — Every `aliyun` CLI command invocation must include:
`--user-agent AlibabaCloud-Agent-Skills/alibabacloud-chatapp-message-send`

**[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-chatapp-message-send"
```

**[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
```

### 2. Install cams Plugin

```bash
aliyun plugin install --names aliyun-cli-cams
```

### 3. Credential Verification

> **Pre-check: Alibaba Cloud Credentials Required**
>
> **Security Rules:**
>
> - **NEVER** read, echo, or print AK/SK values
> - **NEVER** ask the user to input AK/SK directly in the conversation or command line
> - **NEVER** use `aliyun configure set` with literal credential values
> - **ONLY** use `aliyun configure list` to check credential status
>
> ```bash
> aliyun configure list
> ```
>
> Check the output for a valid profile (AK, STS, or OAuth identity).
>
> **If no valid profile exists, STOP here.**
>
> 1. Obtain credentials from [Alibaba Cloud Console](https://ram.console.aliyun.com/manage/ak)
> 2. Configure credentials **outside of this session** (via `aliyun configure` in terminal or environment variables in shell profile)
> 3. Return and re-run after `aliyun configure list` shows a valid profile

### 4. Enable Chat App Message Service

Complete the following in the [Alibaba Cloud Console](https://cams.console.aliyun.com/):

1. Enable Chat App Message Service
2. Bind a WhatsApp Business Account (WABA)
3. Register and get the sender phone number approved (From)
4. Create and get message templates approved (required for template messages)

## Usage

### Direct aliyun CLI

**Send a template message:**

```bash
aliyun cams send-chatapp-message \
  --channel-type whatsapp \
  --type template \
  --from "86138xxxx" \
  --to "86139xxxx" \
  --template-code "hello_world" \
  --biz-language "en" \
  --template-params 1=Alice 2=Bob \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-chatapp-message-send
```

**Send a custom text message:**

```bash
aliyun cams send-chatapp-message \
  --channel-type whatsapp \
  --type message \
  --from "86138xxxx" \
  --to "86139xxxx" \
  --message-type text \
  --content '{"text":"Hello, this is a test message"}' \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-chatapp-message-send
```

**List approved templates:**

```bash
aliyun cams list-chatapp-template \
  --audit-status pass \
  --template-type WHATSAPP \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-chatapp-message-send
```

**Get template detail:**

```bash
aliyun cams get-chatapp-template-detail \
  --template-code "hello_world" \
  --biz-language "en" \
  --template-type WHATSAPP \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-chatapp-message-send
```

### Using Wrapper Scripts

This skill provides Python wrapper scripts for simplified invocation with pre-send confirmation.

**List approved templates:**

```bash
python scripts/list_templates.py --audit-status pass --template-type WHATSAPP
```

**Get template detail (view variable structure):**

```bash
python scripts/get_template_detail.py --template-code hello_world --language en
```

**Send a template message (with confirmation):**

```bash
python scripts/send_chatapp_message.py send-template \
  --from "86138xxxx" --to "86139xxxx" \
  --template-code hello_world --language en \
  --template-params 1=Alice 2=Bob
```

**Send a custom message (with confirmation):**

```bash
python scripts/send_chatapp_message.py send-message \
  --from "86138xxxx" --to "86139xxxx" \
  --message-type text \
  --content '{"text":"Hello"}'
```

**Skip confirmation and send directly:**

```bash
python scripts/send_chatapp_message.py send-template ... --yes
```

**Preview command only (dry-run):**

```bash
python scripts/send_chatapp_message.py send-template ... --dry-run
```

## Parameter Reference

### aliyun cams send-chatapp-message Parameters

| Parameter         | Required              | Description                                                                                                  |
| ----------------- | --------------------- | ------------------------------------------------------------------------------------------------------------ |
| --channel-type    | Yes                   | Channel type:`whatsapp` / `viber`                                                                        |
| --type            | Yes                   | Message type:`template` (template message) / `message` (custom message)                                  |
| --from            | Yes                   | Sender phone number, numeric digits only, must be registered and approved in console (e.g.`8613867404376`) |
| --to              | Yes                   | Recipient phone number, numeric digits with country code**without `+`** (e.g. `8619521605234`)     |
| --template-code   | Required for template | Template code                                                                                                |
| --biz-language    | Required for template | Template language, e.g.`en`, `zh_CN`                                                                     |
| --template-params | No                    | Template variables in format `key=value`, multiple separated by spaces                                     |
| --message-type    | Required for custom   | Content type:`text`/`image`/`video`/`audio`/`document`/`interactive`/`location` etc.           |
| --content         | Required for custom   | Message content as a JSON string                                                                             |
| --cust-space-id   | No                    | ISV account space ID                                                                                         |
| --user-agent      | Yes                   | Fixed value `AlibabaCloud-Agent-Skills/alibabacloud-chatapp-message-send`                                  |

### Custom Message Content JSON Formats

The `--content` parameter is a JSON string; format varies by message-type:

- **text**: `{"text":"Message content"}`
- **image**: `{"link":"https://example.com/img.jpg","caption":"Description"}`
- **video**: `{"link":"https://example.com/vid.mp4","caption":"Description"}`
-