byted-sms-sender

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Byted SMS Sender

火山引擎短信服务 API,版本 2026-01-01

Volcengine SMS Service API, Version 2026-01-01

何时使用

When to Use

当用户有以下需求时,使用本 skill:

发送短信场景:

需要发送验证码短信
需要发送通知类短信
需要发送营销类短信
用户说"发短信""发送验证码""发通知"时

查询场景:

需要查询可用的消息组(子账号)
需要查询已审核通过的短信签名
需要查询已审核通过的短信模板
需要查询短信发送记录
需要查询发送统计(成功率等)

Use this skill when users have the following requirements:

SMS Sending Scenarios:

Need to send verification code SMS
Need to send notification SMS
Need to send marketing SMS
When users say "send SMS", "send verification code", "send notification"

Query Scenarios:

Need to query available message groups (sub-accounts)
Need to query approved SMS signatures
Need to query approved SMS templates
Need to query SMS delivery records
Need to query delivery statistics (success rate, etc.)

使用前检查

Pre-use Check

检查是否已配置以下凭证:

```
ARK_SKILL_API_KEY
```
- API 密钥
```
ARK_SKILL_API_BASE
```
- API 基础地址

这些凭证由 ArkClaw 预先配置在终端环境中，配置文件位置:

/root/.openclaw/.env

检查方式:

bash

echo $ARK_SKILL_API_KEY
echo $ARK_SKILL_API_BASE

如果缺少凭证:

检查配置文件
```
/root/.openclaw/.env
```
是否存在
如果仍然找不到，请联系 oncall 获取帮助

Check if the following credentials have been configured:

```
ARK_SKILL_API_KEY
```
- API key
```
ARK_SKILL_API_BASE
```
- API base URL

These credentials are pre-configured in the terminal environment by ArkClaw, configuration file path:

/root/.openclaw/.env

Check method:

bash

echo $ARK_SKILL_API_KEY
echo $ARK_SKILL_API_BASE

If credentials are missing:

Check if the configuration file
```
/root/.openclaw/.env
```
exists
If you still cannot find it, contact oncall for help

6个接口说明

6 API Descriptions

1. send_sms - 发送短信

1. send_sms - Send SMS

场景: 用户需要发送验证码、通知、营销短信

使用方式:

bash

python3 scripts/volc_sms.py send_sms \
  --sub-account "消息组ID" \
  --signature "签名" \
  --template-id "模板ID" \
  --mobiles "手机号" \
  --template-param '{"code":"123456"}'

参数说明:

```
--sub-account
```
: 消息组ID(必填),从 list_sub_account 获取
```
--signature
```
: 短信签名(必填),从 list_signature 获取
```
--template-id
```
: 模板ID(必填),从 list_sms_template 获取
```
--mobiles
```
: 手机号(必填),多个用逗号分隔
```
--template-param
```
: 模板参数(可选),JSON格式

Scenario: Users need to send verification codes, notifications, and marketing SMS

Usage:

bash

python3 scripts/volc_sms.py send_sms \
  --sub-account "消息组ID" \
  --signature "签名" \
  --template-id "模板ID" \
  --mobiles "手机号" \
  --template-param '{"code":"123456"}'

Parameter Description:

```
--sub-account
```
: Message group ID (required), obtained from list_sub_account
```
--signature
```
: SMS signature (required), obtained from list_signature
```
--template-id
```
: Template ID (required), obtained from list_sms_template
```
--mobiles
```
: Mobile phone number (required), separate multiple numbers with commas
```
--template-param
```
: Template parameters (optional), JSON format

2. list_sub_account - 查询消息组

2. list_sub_account - Query Message Groups

场景: 需要知道可以用哪个消息组发送短信

使用方式:

bash

python3 scripts/volc_sms.py list_sub_account

参数说明:

```
--sub-account-name
```
: 可选,按名称模糊搜索

Scenario: Need to know which message group can be used to send SMS

Usage:

bash

python3 scripts/volc_sms.py list_sub_account

Parameter Description:

```
--sub-account-name
```
: Optional, fuzzy search by name

3. list_signature - 查询签名

3. list_signature - Query Signatures

场景: 需要知道可以用哪个签名,或者查询签名是否审核通过

使用方式:

bash

python3 scripts/volc_sms.py list_signature --signature "火山引擎"

参数说明:

```
--signature
```
: 可选,按签名模糊搜索
```
--sub-accounts
```
: 可选,按子账号过滤
```
--page
```
: 页码,默认1
```
--page-size
```
: 每页数量,默认20

Scenario: Need to know which signature can be used, or check if a signature has been approved

Usage:

bash

python3 scripts/volc_sms.py list_signature --signature "火山引擎"

Parameter Description:

```
--signature
```
: Optional, fuzzy search by signature
```
--sub-accounts
```
: Optional, filter by sub-account
```
--page
```
: Page number, default 1
```
--page-size
```
: Number of items per page, default 20

4. list_sms_template - 查询模板

4. list_sms_template - Query Templates

场景: 需要知道可以用哪个模板,或者查询模板参数

使用方式:

bash

python3 scripts/volc_sms.py list_sms_template --signatures "火山引擎"

参数说明:

```
--template-id
```
: 可选,按模板ID模糊搜索
```
--signatures
```
: 可选,按签名过滤
```
--sub-accounts
```
: 可选,按子账号过滤
```
--page
```
: 页码,默认1
```
--page-size
```
: 每页数量,默认20

Scenario: Need to know which template can be used, or query template parameters

Usage:

bash

python3 scripts/volc_sms.py list_sms_template --signatures "火山引擎"

Parameter Description:

```
--template-id
```
: Optional, fuzzy search by template ID
```
--signatures
```
: Optional, filter by signature
```
--sub-accounts
```
: Optional, filter by sub-account
```
--page
```
: Page number, default 1
```
--page-size
```
: Number of items per page, default 20

5. list_sms_send_log - 查询发送记录

5. list_sms_send_log - Query Delivery Records

场景: 需要查看某条短信的发送状态,或批量查询发送历史

使用方式:

bash

python3 scripts/volc_sms.py list_sms_send_log \
  --sub-account "消息组ID" \
  --from-time 1773113285 \
  --to-time 1773213285

参数说明:

```
--sub-account
```
: 必填,消息组ID
```
--from-time
```
: 开始时间戳(秒)
```
--to-time
```
: 结束时间戳(秒)
```
--mobile
```
: 可选,按手机号过滤
```
--template-id
```
: 可选,按模板ID过滤
```
--signature
```
: 可选,按签名过滤
```
--message-id
```
: 可选,按消息ID精确查询
```
--page
```
: 页码,默认1
```
--page-size
```
: 每页数量,默认100

Scenario: Need to check the delivery status of a specific SMS, or batch query delivery history

Usage:

bash

python3 scripts/volc_sms.py list_sms_send_log \
  --sub-account "消息组ID" \
  --from-time 1773113285 \
  --to-time 1773213285

Parameter Description:

```
--sub-account
```
: Required, message group ID
```
--from-time
```
: Start timestamp (seconds)
```
--to-time
```
: End timestamp (seconds)
```
--mobile
```
: Optional, filter by mobile phone number
```
--template-id
```
: Optional, filter by template ID
```
--signature
```
: Optional, filter by signature
```
--message-id
```
: Optional, exact query by message ID
```
--page
```
: Page number, default 1
```
--page-size
```
: Number of items per page, default 100

6. list_total_send_count_stat - 查询发送统计

6. list_total_send_count_stat - Query Delivery Statistics

场景: 需要查看发送成功率、接收成功率等统计信息

使用方式:

bash

python3 scripts/volc_sms.py list_total_send_count_stat \
  --start-time 1773113285 \
  --end-time 1773213285

参数说明:

```
--start-time
```
: 必填,开始时间戳(秒)
```
--end-time
```
: 必填,结束时间戳(秒)
```
--sub-account
```
: 可选,按消息组过滤
```
--channel-type
```
: 可选,通道类型
```
--signature
```
: 可选,按签名过滤
```
--template-id
```
: 可选,按模板ID过滤

返回字段:

TotalSendCount: 总发送数
TotalSendSuccessCount: 发送成功数
TotalSendSuccessRate: 发送成功率
TotalReceiptSuccessCount: 接收成功数
TotalReceiptSuccessRate: 接收成功率

Scenario: Need to view statistical information such as delivery success rate, receipt success rate, etc.

Usage:

bash

python3 scripts/volc_sms.py list_total_send_count_stat \
  --start-time 1773113285 \
  --end-time 1773213285

Parameter Description:

```
--start-time
```
: Required, start timestamp (seconds)
```
--end-time
```
: Required, end timestamp (seconds)
```
--sub-account
```
: Optional, filter by message group
```
--channel-type
```
: Optional, channel type
```
--signature
```
: Optional, filter by signature
```
--template-id
```
: Optional, filter by template ID

Return Fields:

TotalSendCount: Total number of sent messages
TotalSendSuccessCount: Number of successfully sent messages
TotalSendSuccessRate: Delivery success rate
TotalReceiptSuccessCount: Number of successfully received messages
TotalReceiptSuccessRate: Receipt success rate

典型使用流程

Typical Usage Process

第一次发送短信

Sending SMS for the First Time

查询可用的消息组

bash

python3 scripts/volc_sms.py list_sub_account

查询可用的签名

bash

python3 scripts/volc_sms.py list_signature

查询可用的模板

bash

python3 scripts/volc_sms.py list_sms_template --signatures "火山引擎"

发送短信

bash

python3 scripts/volc_sms.py send_sms \
  --sub-account "xxxx" \
  --signature "xxx" \
  --template-id "ST_xxxx" \
  --mobiles "188xxxxxxx8" \
  --template-param '{"code":"888888"}'

Query available message groups

bash

python3 scripts/volc_sms.py list_sub_account

Query available signatures

bash

python3 scripts/volc_sms.py list_signature

Query available templates

bash

python3 scripts/volc_sms.py list_sms_template --signatures "火山引擎"

Send SMS

bash

python3 scripts/volc_sms.py send_sms \
  --sub-account "xxxx" \
  --signature "xxx" \
  --template-id "ST_xxxx" \
  --mobiles "188xxxxxxx8" \
  --template-param '{"code":"888888"}'

查询发送状态

Query Delivery Status

bash

python3 scripts/volc_sms.py list_sms_send_log \
  --sub-account "77da1acf" \
  --from-time 1773113285 \
  --to-time 1773213285

bash

python3 scripts/volc_sms.py list_sms_send_log \
  --sub-account "77da1acf" \
  --from-time 1773113285 \
  --to-time 1773213285

常见错误码

Common Error Codes

```
RE:0001
```
: 账号短信服务未开通
```
RE:0003
```
: 子账号不存在(消息组ID错误)
```
RE:0004
```
: 签名错误(签名不存在或未审核通过)
```
RE:0005
```
: 模板错误(模板不存在或未审核通过)
```
RE:0006
```
: 手机号格式错误
```
RE:0010
```
: 账号欠费
```
ZJ10200
```
: 请求参数错误

```
RE:0001
```
: SMS service is not activated for the account
```
RE:0003
```
: Sub-account does not exist (incorrect message group ID)
```
RE:0004
```
: Signature error (signature does not exist or has not been approved)
```
RE:0005
```
: Template error (template does not exist or has not been approved)
```
RE:0006
```
: Incorrect mobile phone number format
```
RE:0010
```
: Account is in arrears
```
ZJ10200
```
: Request parameter error

注意事项

Notes

签名和模板: 必须使用已审核通过的签名和模板
手机号格式:
- 国内短信: 11位手机号或 +86开头
- 国际短信: 必须包含国际区号,符合 E.164 标准
批量限制: 单次最多200个手机号
签名子账号匹配: 签名和消息组需要匹配,可从 list_signature 的 SubAccounts 字段确认
模板签名匹配: 模板和签名需要匹配,可从 list_sms_template 的 Signature 字段确认

Signatures and templates: Only approved signatures and templates can be used
Mobile phone number format:
- Domestic SMS: 11-digit mobile number or starts with +86
- International SMS: Must include international area code, comply with E.164 standard
Batch limit: Maximum 200 mobile numbers per single request
Signature and sub-account matching: Signature and message group must match, you can confirm from the SubAccounts field of list_signature
Template and signature matching: Template and signature must match, you can confirm from the Signature field of list_sms_template

故障排查

Troubleshooting

缺少凭证: 检查
```
/root/.openclaw/.env
```
文件，如仍找不到请联系 oncall
发送失败: 先用 list_sub_account、list_signature、list_sms_template 确认参数正确
鉴权失败: 检查自己配置的 AK/SK 是否开通正确
权限错误: 检查凭证是否正确，如问题持续请联系 oncall
欠费错误: 请联系 oncall 处理

Missing credentials: Check the
```
/root/.openclaw/.env
```
file, if you still cannot find it, contact oncall
Sending failed: First use list_sub_account, list_signature, list_sms_template to confirm the parameters are correct
Authentication failed: Check whether the configured AK/SK is activated correctly
Permission error: Check whether the credentials are correct, if the problem persists, contact oncall
Arrears error: Please contact oncall for handling