Byted SMS Sender
火山引擎短信服务 API,版本 2026-01-01
何时使用
当用户有以下需求时,使用本 skill:
发送短信场景:
- 需要发送验证码短信
- 需要发送通知类短信
- 需要发送营销类短信
- 用户说"发短信""发送验证码""发通知"时
查询场景:
- 需要查询可用的消息组(子账号)
- 需要查询已审核通过的短信签名
- 需要查询已审核通过的短信模板
- 需要查询短信发送记录
- 需要查询发送统计(成功率等)
使用前检查
检查是否已配置以下凭证:
VOLCENGINE_ACCESS_KEY+VOLCENGINE_SECRET_KEY
如果缺少凭证,打开 references/setup-guide.md 查看开通、申请和配置方式,并给予用户开通建议。
6个接口说明
1. send_sms - 发送短信
场景: 用户需要发送验证码、通知、营销短信
使用方式:
python3 scripts/volc_sms.py send_sms \
--access-key "AKLT..." \
--secret-key "Wm1..." \
--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格式
2. list_sub_account - 查询消息组
场景: 需要知道可以用哪个消息组发送短信
使用方式:
python3 scripts/volc_sms.py list_sub_account \
--access-key "AKLT..." \
--secret-key "Wm1..."参数说明:
--sub-account-name: 可选,按名称模糊搜索
3. list_signature - 查询签名
场景: 需要知道可以用哪个签名,或者查询签名是否审核通过
使用方式:
python3 scripts/volc_sms.py list_signature \
--access-key "AKLT..." \
--secret-key "Wm1..." \
--signature "火山引擎"参数说明:
--signature: 可选,按签名模糊搜索--sub-accounts: 可选,按子账号过滤--page: 页码,默认1--page-size: 每页数量,默认20
4. list_sms_template - 查询模板
场景: 需要知道可以用哪个模板,或者查询模板参数
使用方式:
python3 scripts/volc_sms.py list_sms_template \
--access-key "AKLT..." \
--secret-key "Wm1..." \
--signatures "火山引擎"参数说明:
--template-id: 可选,按模板ID模糊搜索--signatures: 可选,按签名过滤--sub-accounts: 可选,按子账号过滤--page: 页码,默认1--page-size: 每页数量,默认20
5. list_sms_send_log - 查询发送记录
场景: 需要查看某条短信的发送状态,或批量查询发送历史
使用方式:
python3 scripts/volc_sms.py list_sms_send_log \
--access-key "AKLT..." \
--secret-key "Wm1..." \
--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
6. list_total_send_count_stat - 查询发送统计
场景: 需要查看发送成功率、接收成功率等统计信息
使用方式:
python3 scripts/volc_sms.py list_total_send_count_stat \
--access-key "AKLT..." \
--secret-key "Wm1..." \
--start-time 1773113285 \
--end-time 1773213285参数说明:
--start-time: 必填,开始时间戳(秒)--end-time: 必填,结束时间戳(秒)--sub-account: 可选,按消息组过滤--channel-type: 可选,通道类型--signature: 可选,按签名过滤--template-id: 可选,按模板ID过滤
返回字段:
- TotalSendCount: 总发送数
- TotalSendSuccessCount: 发送成功数
- TotalSendSuccessRate: 发送成功率
- TotalReceiptSuccessCount: 接收成功数
- TotalReceiptSuccessRate: 接收成功率
典型使用流程
第一次发送短信
- 查询可用的消息组
python3 scripts/volc_sms.py list_sub_account --access-key AKLT... --secret-key "Wm1..." - 查询可用的签名
python3 scripts/volc_sms.py list_signature --access-key AKLT... --secret-key "Wm1..." - 查询可用的模板
python3 scripts/volc_sms.py list_sms_template --access-key AKLT... --secret-key "Wm1..." --signatures "火山引擎" - 发送短信
python3 scripts/volc_sms.py send_sms --access-key AKLT... --secret-key "Wm1..." \ --sub-account "77da1acf" \ --signature "火山引擎" \ --template-id "ST_85087022" \ --mobiles "18810792528" \ --template-param '{"code":"888888"}'
查询发送状态
python3 scripts/volc_sms.py list_sms_send_log --access-key AKLT... --secret-key "Wm1..." \
--sub-account "77da1acf" \
--from-time 1773113285 \
--to-time 1773213285常见错误码
RE:0001: 账号短信服务未开通RE:0003: 子账号不存在(消息组ID错误)RE:0004: 签名错误(签名不存在或未审核通过)RE:0005: 模板错误(模板不存在或未审核通过)RE:0006: 手机号格式错误RE:0010: 账号欠费ZJ10200: 请求参数错误
注意事项
- 签名和模板: 必须使用已审核通过的签名和模板
- 手机号格式:
- 国内短信: 11位手机号或 +86开头 - 国际短信: 必须包含国际区号,符合 E.164 标准
- 批量限制: 单次最多200个手机号
- 签名子账号匹配: 签名和消息组需要匹配,可从 list_signature 的 SubAccounts 字段确认
- 模板签名匹配: 模板和签名需要匹配,可从 list_sms_template 的 Signature 字段确认
故障排查
- 缺少凭证: 打开
references/setup-guide.md - 发送失败: 先用 list_sub_account、list_signature、list_sms_template 确认参数正确
- 权限错误: 检查服务是否已开通、凭证是否有效,子账号是否已授权
- 欠费错误: 通过
references/setup-guide.md指导用户充值