发送消息

给某个已绑定客户发送一条消息(系统通知或 OTP 投递)。

POST /api/v1/merchant/message/send

请求头

需带 X-Api-Key、X-Api-Secret、Idempotency-Key(见认证)。

请求体

字段	类型	必填	说明
customerExternalId	string	✅	你方系统的客户 ID
category	string	❌	NOTIFICATION(默认)或 OTP,仅用于分类统计
text	string	✅*	直接文本;与 templateCode 二选一
templateCode	string	✅*	已批准的模板编码;与 text 二选一
variables	object	❌	模板变量,如 {"otp":"395217"}

text 与 templateCode 至少提供一个。用模板时,LOMA 会用 variables 渲染模板中的 {占位符}。

示例(直接文本)

{
  "customerExternalId": "C10086",
  "category": "OTP",
  "text": "您的验证码是 395217,5 分钟内有效。"
}

示例(使用模板)

{
  "customerExternalId": "C10086",
  "category": "OTP",
  "templateCode": "otp_msg",
  "variables": { "otp": "395217", "minutes": 5 }
}

成功响应 200

{
  "code": "OK",
  "message": "Success",
  "requestId": "req_...",
  "data": {
    "messageRequestId": "2072...014",
    "status": "SENT"
  }
}

• messageRequestId:消息请求 ID,可用查询状态。
• status:QUEUED / SENT / FAILED。

主要错误

code	HTTP	说明
CUSTOMER_NOT_BOUND	409	客户未绑定 LINE
CUSTOMER_UNFOLLOWED	409	客户未加官方账号好友,无法推送
TEMPLATE_NOT_FOUND	404	模板不存在或未批准
TEMPLATE_VAR_MISSING	400	模板变量缺失
QUOTA_EXCEEDED	429	本月消息配额已用尽
VALIDATION_ERROR	400	参数校验失败

完整错误码见错误码。