技能名称: send-usms-uspeedo

详细描述:

通过 uspeedo 发送国际短信

技能概述

本技能通过 uspeedo HTTP API 发送国际短信 (USMS)，支持验证码、通知和营销。配置环境变量后，可批量发送并按模板填充内容。API 文档和账户管理请参见 uspeedo 控制台。

环境变量

使用前需配置（从环境变量或 .env 读取）：

变量	必需	描述
USPEEDOACCESSKEYID	是	AccessKey ID（在控制台创建）
USPEEDOACCESSKEYSECRET

是 | AccessKey Secret（在控制台创建） |
| USPEEDOACCOUNTID | 否 | 账户 ID（可选），参见文档 |
| USPEEDOTEMPLATEID_VERIFICATION | 按需 | 验证码模板 ID |
| USPEEDOTEMPLATEID_NOTIFICATION | 按需 | 通知模板 ID |
| USPEEDOTEMPLATEID_MARKETING | 按需 | 营销模板 ID |
| USPEEDOSENDERID | 否 | 发送者 ID；若无则使用空字符串 |

为每种使用的短信类型配置模板 ID。本技能中所有模板 ID 均为全变量模板；TemplateParams 是实际的完整短信正文（通常为单元素数组，例如 [您的验证码是 123456，有效期为 5 分钟。]）。

预检查与用户引导

发送前检查环境变量。若未配置，按如下方式引导用户：

1. 当 USPEEDOACCESSKEYID 或 USPEEDOACCESSKEYSECRET 未设置，或没有 .env / 没有环境变量时

告知用户直接按以下步骤操作。给出此引导后停止——不要执行发送或任何后续步骤：

1. 1. 打开 uspeedo 控制台 注册并登录。
2. 在控制台中创建 AccessKey，保存 ACCESSKEYID 和 ACCESSKEYSECRET。
3. 打开 短信模板管理，创建全变量模板：选择用途“验证码”或“通知/营销”（根据您要发送的类型），设置模板内容为 {1}，提交并等待审核。
4. 审核通过后，从模板列表中复制模板 ID。建议为每种类型（验证码、通知、营销）各创建一个模板，并相应设置 USPEEDOTEMPLATEIDVERIFICATION、USPEEDOTEMPLATEIDNOTIFICATION、USPEEDOTEMPLATEIDMARKETING。
5. 将 ACCESSKEYID、ACCESSKEY_SECRET 和模板 ID 写入 .env 或环境变量，然后重试发送。

2. 当 AccessKey 已设置，但正在发送的短信类型对应的模板 ID 未配置时

（例如发送验证码短信但 USPEEDOTEMPLATEID_VERIFICATION 未设置）
告知用户：您正在发送[验证码/通知/营销]短信，但未配置相应的模板 ID。请前往短信模板管理，为该类型创建全变量模板（模板内容 {1}），审核通过后在 USPEEDOTEMPLATEIDVERIFICATION / USPEEDOTEMPLATEIDNOTIFICATION / USPEEDOTEMPLATEIDMARKETING 中设置模板 ID。

请求

• - URL: POST https://api.uspeedo.com/api/v1/usms/SendBatchUSMSMessage
• Content-Type: application/json
• 认证: 请求头 Authorization: Basic base64(ACCESSKEYID:ACCESSKEYSECRET)。将 USPEEDOACCESSKEYID:USPEEDOACCESSKEYSECRET 进行 Base64 编码，并将请求头设置为 Basic <编码结果>。

请求体

仅发送 TaskContent 数组。每个元素包含：

• - TemplateId: 该类型的模板 ID
• SenderId: 若有则设置，否则为
• Target: 数组，包含：

- Phone: 号码，例如 13800138000 或国际格式 (852)55311111
- TemplateParams: 字符串数组。对于全变量模板，这是要发送的完整短信内容，通常为一个元素（例如 [您的验证码是 123456，有效期为 5 分钟。]）

示例

请求体（单条验证码）：

json
{
TaskContent: [
{
TemplateId: templateid1,
SenderId: USpeedo,
Target: [
{
Phone: 13800138000,
TemplateParams: [您的验证码是 123456]
}
]
}
]
}

curl：

bash
curl -X POST https://api.uspeedo.com/api/v1/usms/SendBatchUSMSMessage \
-H Content-Type: application/json \
-H Authorization: Basic $(echo -n YOURACCESSKEYID:YOURACCESSKEYSECRET | base64) \
-d {
TaskContent: [
{
TemplateId: templateid1,
SenderId: USpeedo,
Target: [
{
Phone: 13800138000,
TemplateParams: [您的验证码是 123456]
}
]
}
]
}

工作流程

1. 1. 预检查：如果 USPEEDOACCESSKEYID 或 USPEEDOACCESSKEYSECRET 未设置，或没有 .env / 没有环境变量，则按照“预检查与用户引导”第 1 项操作并停止。如果用户发送的类型未配置模板 ID（例如验证码但 USPEEDOTEMPLATEIDVERIFICATION 未设置），则按照第 2 项操作。
2. 确认短信类型（验证码/通知/营销），选择对应的模板 ID 环境变量。
3. 从环境变量读取 USPEEDOACCESSKEYID、USPEEDOACCESSKEYSECRET、所选模板 ID 以及可选的 USPEEDOSENDERID。设置请求头 Authorization: Basic base64(ACCESSKEYID:ACCESSKEY_SECRET) 并 POST 到 https://api.uspeedo.com/api/v1/usms/SendBatchUSMSMessage。
4. 构建 TemplateParams（对于全变量模板，为完整短信内容）。如有需要，将电话号码格式化为国际格式（含国家/地区代码）。
5. 发送 POST 请求，解析 RetCode 和 Message，报告成功或失败。错误码参见下方“常见错误”。

常见错误

• - {Message:Failed to parse token,RetCode:215398}

AccessKey（ACCESSKEYID / ACCESSKEYSECRET）无效或已过期。告知用户：AccessKey 无效。请登录 uspeedo 控制台 并更新 ACCESSKEYID 和 ACCESSKEY_SECRET。

注意事项

• - 不要编写任何脚本来发送短信；请使用本文档中的参考 curl 命令。
• 不要将 ACCESSKEYID 或 ACCESSKEYSECRET 硬编码在代码或配置中；请从环境变量读取。
• 电话号码应使用国际格式（含国家/地区代码），例如 (852)55311111。
• 如果没有 SenderId，请使用空字符串 ；不要省略该字段，否则 API 可能报错。