瀑布消息开放平台

# 发送消息

发送消息是瀑布消息平台的核心功能。支持GET和POST两种请求方式，推荐使用POST方式。

# 📋 API概览

# 基础信息

  • 接口地址: GET/POST https://waterfallapi.zhaoyizhe.com/waterfall/wapi/send
  • 请求方式: GET / POST（推荐POST）
  • 认证方式: 通过 accessSecret 参数认证
  • 请求格式: GET参数 / JSON
  • 响应格式: JSON

# 请求头设置（POST请求）

Content-Type: application/json

# 📝 请求参数

# 参数说明

参数 类型 必需 说明 示例
accessSecret string ✅ 应用密钥 5dae3031043e4.....60754
templateId string ✅ 模板ID 4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s
affiliatedJson string ✅ 模板变量内容，JSON字符串格式 详见下方说明
pushRange integer ✅ 发送范围
1：全部用户
2：指定用户		 1
pushIds string ❌ 目标用户ID，多个用户用逗号分隔
pushRange=2时必填		 user_001,user_002,user_003
pushTimeType integer ✅ 发送时间类型
1：立即发送
2：定时发送		 1
pushTime string ❌ 定时发送时间
pushTimeType=2时必填
格式：yyyy-MM-dd HH:mm:ss		 2025-07-05 12:30:22
messageInfo string ❌ 消息详情，HTML格式，用于消息详情页面 <p>这是消息详情</p>

# affiliatedJson 参数详解

affiliatedJson 是一个JSON字符串，用于填充模板变量。格式如下：

[
  {
    "key": "${title}",
    "value": "待签收"
  },
  {
    "key": "${field_2}", 
    "value": "SF3284920349"
  },
  {
    "key": "${field_3}",
    "value": "2025-09-11 12:21"
  }
]
  • key: 模板中定义的变量键名（如 ${title}）
  • value: 要替换的实际值

# 📤 请求示例

# POST 请求（推荐）

// JavaScript 示例
const sendData = {
  accessSecret: "5dae3031043e4.....60754",
  templateId: "4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s",
  affiliatedJson: JSON.stringify([
    {"key": "${title}", "value": "待签收"},
    {"key": "${field_2}", "value": "SF3284920349"},
    {"key": "${field_3}", "value": "2025-09-11 12:21"}
  ]),
  pushRange: 1,
  pushTimeType: 1,
  messageInfo: "<p>您的快递正在配送中，请注意查收。</p>"
};

const response = await fetch('https://waterfallapi.zhaoyizhe.com/waterfall/wapi/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(sendData)
});

const result = await response.json();

# Python 示例
import requests
import json

url = "https://waterfallapi.zhaoyizhe.com/waterfall/wapi/send"

data = {
    "accessSecret": "5dae3031043e4.....60754",
    "templateId": "4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s",
    "affiliatedJson": json.dumps([
        {"key": "${title}", "value": "待签收"},
        {"key": "${field_2}", "value": "SF3284920349"},
        {"key": "${field_3}", "value": "2025-09-11 12:21"}
    ]),
    "pushRange": 1,
    "pushTimeType": 1,
    "messageInfo": "<p>您的快递正在配送中，请注意查收。</p>"
}

response = requests.post(url, json=data)
result = response.json()

# GET 请求

# 立即发送给所有用户
GET https://waterfallapi.zhaoyizhe.com/waterfall/wapi/send?accessSecret=5dae3031043e4.....60754&templateId=4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s&affiliatedJson=%5B%7B%22key%22%3A%22%24%7Btitle%7D%22%2C%22value%22%3A%22%E5%BE%85%E7%AD%BE%E6%94%B6%22%7D%5D&pushRange=1&pushTimeType=1

# 定时发送给指定用户
GET https://waterfallapi.zhaoyizhe.com/waterfall/wapi/send?accessSecret=5dae3031043e4.....60754&templateId=4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s&affiliatedJson=%5B%7B%22key%22%3A%22%24%7Btitle%7D%22%2C%22value%22%3A%22%E5%BE%85%E7%AD%BE%E6%94%B6%22%7D%5D&pushRange=2&pushIds=user_001,user_002&pushTimeType=2&pushTime=2025-07-05%2012:30:22

GET请求注意

使用GET请求时，affiliatedJson 参数必须进行URL编码！

# 📊 响应格式

# 成功响应

{
  "code": 1,
  "message": "操作成功！"
}

# 错误响应

当请求失败时，会返回相应的错误码和错误信息：

{
  "code": 10003,
  "message": "应用密钥不能为空，字段：accessSecret"
}

# 🔧 使用示例

# 1. 立即发送给所有用户

async function sendToAllUsers(accessSecret, templateId, templateData) {
  const sendData = {
    accessSecret: accessSecret,
    templateId: templateId,
    affiliatedJson: JSON.stringify(templateData),
    pushRange: 1,
    pushTimeType: 1
  };

  try {
    const response = await fetch('https://waterfallapi.zhaoyizhe.com/waterfall/wapi/send', {
      method: 'POST',
      headers: {'Content-Type': 'application/json'},
      body: JSON.stringify(sendData)
    });
    
    const result = await response.json();
    return result.code === 1;
  } catch (error) {
    console.error('发送失败:', error);
    return false;
  }
}

// 使用示例
const templateData = [
  {"key": "${title}", "value": "系统维护通知"},
  {"key": "${content}", "value": "系统将于今晚22:00-24:00进行维护"}
];
await sendToAllUsers('your_access_secret', 'template_id', templateData);

# 2. 定时发送给指定用户

import requests
import json
from datetime import datetime, timedelta

def send_to_specific_users(access_secret, template_id, user_ids, template_data, send_time):
    """定时发送给指定用户"""
    url = "https://waterfallapi.zhaoyizhe.com/waterfall/wapi/send"
    
    data = {
        "accessSecret": access_secret,
        "templateId": template_id,
        "affiliatedJson": json.dumps(template_data),
        "pushRange": 2,
        "pushIds": ",".join(user_ids),
        "pushTimeType": 2,
        "pushTime": send_time.strftime("%Y-%m-%d %H:%M:%S")
    }
    
    response = requests.post(url, json=data)
    result = response.json()
    return result['code'] == 1

# 使用示例
template_data = [
    {"key": "${title}", "value": "生日祝福"},
    {"key": "${name}", "value": "张先生"},
    {"key": "${gift}", "value": "9折优惠券"}
]

# 明天中午12点发送
send_time = datetime.now() + timedelta(days=1)
send_time = send_time.replace(hour=12, minute=0, second=0)

success = send_to_specific_users(
    'your_access_secret',
    'birthday_template_id', 
    ['user_001', 'user_002'],
    template_data,
    send_time
)

# 3. 带详情的消息发送

async function sendWithDetail(accessSecret, templateId, templateData, messageDetail) {
  const sendData = {
    accessSecret: accessSecret,
    templateId: templateId,
    affiliatedJson: JSON.stringify(templateData),
    pushRange: 1,
    pushTimeType: 1,
    messageInfo: messageDetail
  };

  const response = await fetch('https://waterfallapi.zhaoyizhe.com/waterfall/wapi/send', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify(sendData)
  });
  
  return await response.json();
}

// 使用示例
const templateData = [
  {"key": "${title}", "value": "新产品发布"},
  {"key": "${product}", "value": "智能手表Pro"}
];

const messageDetail = `
<div style="padding: 20px;">
  <h2>智能手表Pro - 重磅发布</h2>
  <img src="https://example.com/product.jpg" style="width: 100%;" />
  <p>全新智能手表Pro现已发布，配备以下特性：</p>
  <ul>
    <li>7天超长续航</li>
    <li>全天候健康监测</li>
    <li>50米防水设计</li>
    <li>NFC支付功能</li>
  </ul>
  <p><strong>首发价格：¥1,999</strong></p>
  <a href="https://shop.example.com/watch-pro" style="background: #007bff; color: white; padding: 10px 20px; text-decoration: none; border-radius: 5px;">立即购买</a>
</div>
`;

await sendWithDetail('your_access_secret', 'product_template_id', templateData, messageDetail);

# ❗ 注意事项

重要提醒

  1. 频率限制: 每秒最多1000次API调用
  2. 内容限制:
    • 单条消息内容不超过10KB
    • messageInfo 支持HTML格式，会在消息中显示"查看详情"按钮
  3. 用户限制:
    • 批量发送单次最多100个用户
    • 指定用户发送时，pushIds 参数不能为空
  4. 时间限制:
    • 定时发送时间不能早于当前时间
    • 建议定时时间至少比当前时间晚5分钟
  5. 模板匹配:
    • affiliatedJson 中的 key 必须与模板中定义的变量一致
    • 所有模板变量都必须提供对应的值
  6. 编码要求:
    • GET请求时，affiliatedJson 参数必须进行URL编码
    • POST请求时，使用JSON格式，无需额外编码

# 📞 技术支持

如果在发送消息过程中遇到问题：

  • 📧 邮箱: zhangxiao@zhaoyizhe.com
  • 💬 公众号: 瀑布消息

下一步： 错误码说明 | 获取模板列表