创建消息任务
发送接口创建异步任务。是否准备、冻结和提交由参数及客户配置决定，响应受理不等于消息已送达。
接口
HTTP
POST /openapi/v1/messages/send/
Content-Type: application/json
X-API-Key: <API_KEY>
X-Timestamp: <毫秒时间戳>
X-Sign: <签名>主要请求参数
| 参数 | 规则 |
|---|---|
| template_no | 必填，当前客户的有效平台模板编号 |
| phones / recipients | 必须且只能传一种，单次最多 5,000 条 |
| service_account_no | 可选；未传时使用模板绑定的服务号 |
| target_firms | 例如 ["oppo"]；可用范围按已审核资源与通道确认 |
| variable_values | 公共变量字典或数组，p1 至 p18；不能与 recipients 逐号码模式混用 |
| client_request_id | 客户请求 ID，最多 64 字符；建议每个业务发送请求固定一个 ID |
| auto_prepare | 默认 true |
| auto_freeze | 默认 false；true 时 auto_prepare 必须为 true |
| auto_submit | 默认 false；true 时 auto_freeze 必须为 true |
最小请求体（不自动冻结或提交）
JSON
{
"template_no": "TP_EXAMPLE",
"phones": [
"13800138000"
],
"target_firms": [
"oppo"
],
"client_request_id": "your-business-request-001",
"auto_prepare": true,
"auto_freeze": false,
"auto_submit": false
}Python 请求示例
Python
import requests
# headers 使用鉴权文档中的签名示例生成
api_base = os.environ["SMART_MESSAGES_API_BASE"].rstrip("/")
response = requests.post(
f"{api_base}/messages/send/",
headers=headers,
json={
"template_no": "TP_EXAMPLE",
"phones": ["13800138000"],
"target_firms": ["oppo"],
"client_request_id": "your-business-request-001",
"auto_prepare": True,
"auto_freeze": False,
"auto_submit": False,
},
timeout=30,
)
response.raise_for_status()
result = response.json()幂等与未知状态
相同 client_request_id 与相同发送载荷重复请求会返回原任务；同一 ID 对应不同发送载荷会触发幂等冲突。网络异常后先查询原请求，避免用新 ID 无条件重发。submit_unknown 需要核实上游是否受理。