机器人预警通知回调

您需提供回调 URL 注册到猎户星空的系统中，当有机器人预警通知的时候，猎户星空主动回调注册到系统中的回调 URL，用于及时通知您的机器人发生了预警；
默认情况下猎户星空不会进行预警通知，如您需要，请联系猎户星空售前技术支持进行申请，请参考如何申请预警通知回调；
由于回调是异步并行的，因受到您的回调 URL 的响应时间的影响等因素，猎户星空无法保证回调的时序；

请您按照如下步骤来申请预警通知回调：

请按照此文档的说明，准备好您的回调 URL；
登录企业后台（接待后台），在 <预警定制> 功能页面进行如下配置，此步骤您可以自己操作，也可以联系猎户星空的售前技术支持协助您操作：
1. 添加一个新的通知人，此通知人后续将专门用于接收警通知回调（下面简称：专用通知人），姓名填写：预警通知回调专用，手机号请暂时填写您能收到短信的手机号（此手机号仅用于配置过程中的测试验证，后续正式配置好回调 URL 之后此手机号会被修改成回调 URL，请您不用担心正式配置好回调 URL 之后收到您不想收到的短信）；
2. 根据您的需要来配置需要回调的预警，例如：离线预警、急停预警等，通知人选择前面添加的专用通知人，并进行测试，如果您收到了符合您预期的预警短信，说明您的配置是正确的，预警的规则请参考预警通知规则；
3. 请您注意：只有配置了上述专用通知人的预警后续才会进行回调，其他没有配置专用通知人的预警不会进行回调；
联系猎户星空的售前技术支持，告知您的回调 URL，猎户星空进行回调 URL 配置，配置完成后，专用通知人的手机号将会被替换成您的回调 URL，在企业后台（接待后台）查看此专用通知人的时候手机号会显示为空；
后续如果您想修改预警通知回调的预警配置，您可以随时修改，只需要把专用通知人配置到您的预警配置中即可收到预警回调；
请注意：请您务必不要修改或删除此专用通知人，否则可能会收不到回调；

新激活（绑定）的机器人在 24 小时内不会发送预警通知短信，也不会进行预警通知回调；
- 这是因为机器人在新激活的 24 小时内一般都处于试运行阶段，初期的运营配置一般都集中在此阶段，可能会有相对频繁的重启和离线，为了防止不必要的预警，猎户星空在机器人激活（绑定）的 24 小时内不会进行预警；
每个机器人的每种类型的预警每天最多预警 3 次，包括预警通知短信和预警通知回调；

回调 URL 可以是 HTTP 地址也可以是 HTTPS 地址，建议使用 HTTPS 地址；
回调 URL 支持携带参数，参数拼接之后最长不能超过 1KB；

当发生预警的时候会立即回调；
多个机器人的同类预警可能会进行合并；
因预警有很强的时效性，所以只会回调一次，失败也不会进行重试；

回调请求 Method	POST
回调请求 Content-Type	application/json
回调超时时间	5秒，响应时间超过 5 秒则放弃本次回调，并且不会重试。

参数	类型	参数说明
open_appid	string	授权账号的 appid
open_code	string	由猎户星空颁发的回调鉴权暗码，用于接入方在收到回调请求之后识别是猎户星空的合法请求，而不是非猎户星空的非法请求。鉴权暗码长度为 32 字节。鉴权暗码不能透漏给第三方。
ov_corpid	string	企业 id
alarm_type	string	预警类型 id，请参考预警类型 alarm_type。
alarm_config	Object	预警配置信息对象，不同的预警类型会有不同的预警配置，请参考预警配置信息对象 alarm_config 和预警信息对象 abnormal_info 中有关 alarm_config 的说明。
alarm_config.start_time	int	`此参数可能不存在，只有包含工作时间配置的预警才包含此参数` 工作开始时间。从 00:00:00 开始的秒数。预警判断使用北京时区来计算，默认是00:00:00。例如 08:00:00 是 28800。
alarm_config.end_time	int	`此参数可能不存在，只有包含工作时间配置的预警才包含此参数` 工作结束时间。从 00:00:00 开始的秒数。预警判断使用北京时区来计算，默认是23:59:59。例如 22:00:00 是 79200。
robot_list	Object[]	预警的机器人和预警信息列表
robot_list[].robot_sn	string	机器人 sn
robot_list[].robot_name	string	机器人名称
robot_list[].abnormal_info	Object	预警信息对象，不同的预警类型会有不同的预警信息，请参考预警配置信息对象 alarm_config 和预警信息对象 abnormal_info 中有关 abnormal_info 的说明。
robot_list[].abnormal_info.ts	int	`此参数可能不存在` 预警发生的时间，整数时间戳，单位是秒，有一些预警类型并没有此参数，当没有此参数的时候建议使用回调的当前时间作为预警时间。例如：1712634136

{
    "open_appid": "test_appid",
    "open_code": "test_code",
    "ov_corpid": "test_ov_corpid",
    "alarm_type": "2",
    "robot_list": [
        {
            "robot_sn":"test_sn",
            "robot_name": "test_name",
            "abnormal_info": {
                // 预警信息对象，请参考 <预警配置信息对象 alarm_config 和预警信息对象 abnormal_info> 章节中有关 abnormal_info 的说明
            }
        }
    ],
    "alarm_config": {
        // 预警配置信息对象，请参考 <预警配置信息对象 alarm_config 和预警信息对象 abnormal_info> 章节中有关 alarm_config 的说明
    }
}

curl --location 'https://your_domain.com/your_callback_url' \
     --header 'Content-Type: application/json' \
     --data '{
    "open_appid": "test_appid",
    "open_code": "test_code",
    "ov_corpid": "test_ov_corpid",
    "alarm_type": "2",
    "robot_list": [
        {
            "robot_sn":"test_sn",
            "robot_name": "test_name",
            "abnormal_info": {
                "battery_rate": 5
            }
        }
    ],
    "alarm_config": {
        "battery_rate": 10
    }
}'

回调响应 HTTP 状态码	200

预警类型 id	预警类型名称	预警简介
1	定位预警	如果机器人在线并发生了定位丢失，则告警。
2	电量预警	如果机器人电量低于设置的百分比（例如 10%），且未处于充电状态，则告警。
3	路径预警	如果机器人在执行运动相关的任务时，持续超过 20 秒路径规划失败，则告警。
4	急停预警	如果机器人在线，且在执行任务时被按了急停，且在设置的时间内（例如 5 分钟）未恢复，则告警。
5	离线预警	如果机器人在设置的工作时间范围内（例如 08:00 - 22:00），离线超过设置的时间（例如 30 分钟），则告警。
6	超时预警	如果机器人在设置的工作时间范围内（例如 08:00 - 22:00），处于在设置的状态中（例如急停）或者正在执行设置的任务（例如导览），且超过设置的时间（例如 30 分钟），则告警。
7	超频预警	如果机器人在设置的工作时间范围内（例如 08:00 - 22:00），在设置的时间内（例如 30 分钟）执行设置的任务（例如导览）超过设置的次数（例如 5 次），则告警。
8	位置预警	如果机器人在设置的工作时间范围内（例如 08:00 - 22:00），超过设置的时间（例如 30 分钟）仍没有到达过设置的地点（例如办公室），则告警。
10	回充预警	如果机器人在自动回冲时，失败次数超过 10 次，则告警。
11	待机预警	如果机器人在设置的工作时间范围内（例如 08:00 - 22:00），持续超过设置的时间（例如 30 分钟）处于未唤醒（表情）状态，则告警。
12	充电异常	如果机器人在充电桩上由于接触不良导致充电缓慢，连续发生设置的次数（例如 3 次），则告警。

预警配置信息对象 alarm_config

无

预警信息对象 abnormal_info

无

预警配置信息对象 alarm_config

参数	类型	参数说明
battery_rate	int	是预警电量百分比阈值，例如 %10 是 10。

预警信息对象 abnormal_info

参数	类型	参数说明
battery_rate	int	是当前电量百分比，例如 %2 是 2。

预警配置信息对象 alarm_config

无

预警信息对象 abnormal_info

无

预警配置信息对象 alarm_config

参数	类型	参数说明
timeout	int	是超时时间，单位是秒。

预警信息对象 abnormal_info

无

预警配置信息对象 alarm_config

参数	类型	参数说明
timeout	int	是超时时间，单位是秒。

预警信息对象 abnormal_info

无

预警配置信息对象 alarm_config

参数	类型	参数说明
task_name	string	`此参数可能不存在` 预警任务类型，例如：导览
state_name	string	`此参数可能不存在` 预警状态类型，例如：急停
timeout	int	是超时时间，单位是秒。

预警信息对象 abnormal_info

参数	类型	参数说明
task_name	string	`此参数可能不存在` 预警任务类型
state_name	string	`此参数可能不存在` 预警状态类型

预警配置信息对象 alarm_config

参数	类型	参数说明
task_name	string	是预警任务类型，例如：导览
frequency	int	是预警频次阈值，例如：2
timeout	int	是超时时间，单位是秒。

预警信息对象 abnormal_info

无

预警配置信息对象 alarm_config

参数	类型	参数说明
pos_name	string	是预警点位
timeout	int	是超时时间，单位是秒。

预警信息对象 abnormal_info

无

预警配置信息对象 alarm_config

无

预警信息对象 abnormal_info

无

预警配置信息对象 alarm_config

参数	类型	参数说明
timeout	int	是超时时间，单位是秒。

预警信息对象 abnormal_info

无

预警配置信息对象 alarm_config

参数	类型	参数说明
frequency	int	是预警频次阈值，例如：5

预警信息对象 abnormal_info

参数	类型	参数说明
battery_rate	int	是当前电量百分比，例如 %2 是 2。

机器人预警通知回调

概述

如何申请预警通知回调

预警通知规则

回调 URL 要求

回调时机

回调请求

回调请求协议

公共回调请求体参数

公共回调请求体示例

回调请求 cURL 示例

回调响应

预警列表

预警类型 alarm_type

预警配置信息对象 alarm_config 和预警信息对象 abnormal_info

定位预警

电量预警

路径预警

急停预警

离线预警

超时预警

超频预警

位置预警

回充预警

待机预警

充电异常