配置平台消息推送

本页目标

配置公网可访问的回调 URL，接收平台 POST 的设备告警、上下线与智能事件；再在自有后台转发给 App 或业务系统。与拉取模式对比见接收设备事件。

前提：回调地址须由开发者后台提供并可被外网访问；字段以 setMessageCallback 等 OpenAPI 页为准。

设置接收消息的回调地址。之后各类事件消息会往这个地址推送。两种设置方式：
- 调用 setMessageCallback：设置报警回调地址。该接口设置开发者账号的消息回调地址。callbackUrl 的说明是：开发者接收设备消息的地址，需要可以被外网访问。status 表示是否订阅消息，合法值为 on、off；status 为 on 时 callbackUrl、callbackFlag 必填，为 off 时可为空。callbackFlag 为事件大类，可多选、逗号分隔：alarm（告警）、deviceStatus（上下线）、capabilityEvent（能力事件与属性上报，报文同接收告警）、iot（IoT）、numberstat（客流）、faceAnalysis（人脸智能）等；完整合法值以 setMessageCallback 与事件消息类型定义为准。basePush 表示该开发者账号下关联的乐橙 App 设备消息是否推送。其余字段约束以对应接口页为准。
- 在控制台消息推送服务设置。界面操作见本页步骤；截图见推送配置 API。
在回调地址接收 POST。类型见事件消息类型定义，示例见事件消息格式定义。业务处理应尽快返回 HTTP 200；若回调长期无有效响应，平台会停止向该地址推送，需修复服务后重新开启订阅（setMessageCallback 或控制台）。

查看当前回调地址，调用 getMessageCallback：查看报警回调地址。获取开发者账号当前设置的消息回调地址；未订阅时 callbackUrl、callbackFlag 为空。教程的两步里没有把这次查询写成必做步骤。

报文：告警、IoT、上下线等字段见事件消息格式定义。callbackFlag 须包含对应大类（如 alarm、deviceStatus、capabilityEvent）；缺订则整类不报。托管 warrantInit/deviceAuthCancel 等见托管事件，须在 callbackFlag 中订阅能承载该类 msgType 的大类（常与 alarm 或业务约定一致，非 capabilityEvent 专属）。
验签：推送 JSON 含 system.sign，与 OpenAPI 相同，按签名用 appSecret 校验后再处理业务。
重试：投递失败时平台会重试，公开文档未固定次数/间隔；回调须幂等。
去重：以报文内消息唯一标识（如 msgId、告警 id）去重，避免重试或重复推送导致重复处理。

设置回调、查看回调和接收推送都在服务端完成。setMessageCallback、getMessageCallback 的参数、请求示例和返回以原接口页为准，字段以各 OpenAPI 方法页为准。推送配置模块说明见推送配置。