Alibabacloud Chatapp Message Send

Prompts

Send WhatsApp messages via Alibaba Cloud Chat App Message Service (CAMS). Supports both template messages and custom (free-form) messages. Use this skill when the user wants to send WhatsApp messages, broadcast notifications, marketing campaigns, verification codes, reply to customer messages, view available message templates, or query template structure and variables.

Install

openclaw skills install alibabacloud-chatapp-message-send

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:

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.

aliyun configure ai-mode disable

2. Install cams Plugin

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
aliyun configure list
Check the output for a valid profile (AK, STS, or OAuth identity).

If no valid profile exists, STOP here.

Obtain credentials from Alibaba Cloud Console

Configure credentials outside of this session (via aliyun configure in terminal or environment variables in shell profile)

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:

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

Usage

Direct aliyun CLI

Send a template message:

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:

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:

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

Get template detail:

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:

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

Get template detail (view variable structure):

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

Send a template message (with confirmation):

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):

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

Skip confirmation and send directly:

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

Preview command only (dry-run):

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 codewithout `+` (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"}
audio: {"link":"https://example.com/aud.mp3"}
document: {"link":"https://example.com/doc.pdf","fileName":"doc.pdf"}
location: {"latitude":"39.9042","longitude":"116.4074","name":"Tiananmen","address":"Beijing"}
interactive: {"type":"button","action":{"buttons":[{"type":"reply","reply":{"id":"btn1","title":"Confirm"}}]}}

Core Workflow and Parameter Confirmation

IMPORTANT: Parameter Confirmation — Before executing any command or API call, ALL user-customizable parameters (e.g., From, To, template code, language, template params, content JSON, etc.) MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.

Template Message Flow

Step 1: Confirm sender and recipient numbers

Sender (From): WhatsApp number registered in the console, numeric digits only without + (e.g. 8613867404376)
Recipient (To): Target user's WhatsApp number, numeric digits with country code without + (e.g. 8619521605234)

Step 2: Select template code

Run python scripts/list_templates.py --audit-status pass to query approved templates
Let the user select a template code from the list

Step 3: Confirm template language

Ask the user for the template language, e.g. en, zh_CN, zh_HK

Step 4: View template variables and guide user to fill them in

Run python scripts/get_template_detail.py --template-code <CODE> --language <LANG>
Based on the variable list in the output, guide the user to fill in each variable value one by one
Variable format: --template-params 1=value1 2=value2 3=value3

Step 5: Confirm before sending

The script automatically summarizes all parameters and displays them for user confirmation
Sending is only executed after the user inputs yes

Custom Message Flow

Step 1: Confirm sender and recipient numbers (same as above)

Step 2: Confirm message type

Ask the user for the message type: text / image / video / audio / document / interactive / location

Step 3: Construct Content JSON based on message type

Based on the selected type, guide the user to provide necessary fields (e.g. text requires text, image requires link, etc.)
Construct the JSON string as the --content parameter

Step 4: Confirm before sending

The script automatically summarizes and displays; sending occurs after user inputs yes

Note: Custom WhatsApp messages can only be sent within the 24-hour session window (within 24 hours after the user's last message). Outside the window, template messages must be used.

Output Reference

Successful Send Response

{
  "Code": "OK",
  "Message": "OK",
  "RequestId": "4C3D8B1B-B3D8-5673-B724-1F251799CE9A",
  "Data": {
    "MessageId": "wamid.xxx"
  }
}

Template List Example

Found 3 templates:

  - hello_world | Welcome Template | Language: en | Status: pass | Category: MARKETING | WHATSAPP
  - otp_verification | OTP | Language: zh_CN | Status: pass | Category: AUTHENTICATION | WHATSAPP

Error Handling

Common Error Codes

Error Code	Description	Resolution
InvalidParameter.FromOnlyNumeric	Phone number contains `+`	API requires pure numeric format, remove `+`, e.g. `8613867404376`
TemplateNotFound	Template does not exist	Confirm template code and language are correct
TemplateParamInvalid	Template variable error	Check variable count and format match the template
SessionWindowExpired	Session window expired	Custom messages must be sent within 24h of user's last reply; use template message instead
PhoneNumberNotRegistered	Sender not registered	Complete phone number registration and approval in console
Forbidden.RAM	Insufficient permissions	Check if RAM user has CAMS permissions

CLI Configuration Errors

Error Message	Cause	Solution
InvalidAccessKeyId.NotFound	Wrong AccessKey ID	Check AccessKey ID
SignatureDoesNotMatch	Wrong Secret	Check AccessKey Secret
Forbidden.RAM	Insufficient permissions	Check RAM user permissions

RAM Permissions

This skill requires RAM permissions for CAMS APIs. See references/ram-policies.md for the complete permission list and minimum policy JSON.

[MUST] Permission Failure Handling: When any command or API call fails due to permission errors at any point during execution, follow this process:

Read references/ram-policies.md to get the full list of permissions required by this SKILL

Use ram-permission-diagnose skill to guide the user through requesting the necessary permissions

Pause and wait until the user confirms that the required permissions have been granted

Notes

Phone Number Format: All numbers must be pure numeric digits with country code but without +. For example: China 8613867404376, US 14155551234. Passing +8613867404376 will raise InvalidParameter.FromOnlyNumeric
Session Window: Custom WhatsApp messages can only be sent within 24 hours after the user's last message. Outside the window, template messages must be used
Template Approval: Template messages must use approved templates (audit-status = pass)
User-Agent: All CLI commands must include --user-agent AlibabaCloud-Agent-Skills/alibabacloud-chatapp-message-send
Credential Security: Never hardcode AK/SK in code or commands
Viber Limitations: Viber messages do not require templates, but have promotion/transaction type restrictions
Content JSON: The --content parameter for custom messages must be a valid JSON string
ISV Scenarios: If using an ISV account, additionally provide --cust-space-id