消息服务

更新时间：2019-07-31 15:00:14

提供一组消息记录的操作服务接口，客户端应用通过本组服务接口可以实现对推送到用户客户端的消息记录的查询、统计和删除等操作。

消息接收

消息查询、删除、更新

消息接收设置

绑定push通道

定义描述

path 版本 描述 是否需要用户身份的鉴权
/uc/bindPushChannel 1.0.2 绑定push通道 是，客户端SDK需启用身份的鉴权

请求参数

参数 类型 必填 描述
deviceId String 是 push通道的deviceId
deviceType String 是 设备类型：iOS或ANDROID，值由业务方和app协商

返回参数

无业务返回参数

示例

请求示例

{
    "request": {
        "iotToken": "109049c80bcde4c06b15f6f62e29a3ba",
        "apiVer": "1.0.2"
    },
    "id": 1508212818676,
    "params": {
        "deviceId":"xxxx",
        "deviceType":"iOS"
    },
    "version": "1.0"
}

正常返回示例

{
    "code": 200,
    "id":"bb179e80-39fd-4a79-ba97-48ca87a3f5c5"
}

异常返回示例

{
 "code":2062,
 "id":"4fa207ca-fffd-48bb-94b8-e6f7ca6c99c3",
 "localizedMsg":"请求错误",
 "message":"identityId not exist"
}

错误码

请参考公共错误码

解绑push通道

定义描述

path 版本 描述 是否需要用户身份的鉴权
/uc/unbindPushChannel 1.0.2 绑定push通道 是，客户端SDK需启用身份的鉴权

请求参数

参数 类型 必填 描述
deviceId String 是 push通道的deviceId

返回参数

无业务返回参数

示例

请求示例

{
    "request": {
        "iotToken": "109049c80bcde4c06b15f6f62e29a3ba",
        "apiVer": "1.0.2"
    },
    "id": 1508212818676,
    "params": {
        "deviceId":"xxxx"
    },
    "version": "1.0"
}

正常返回示例

{
    "code": 200,
    "id":"bb179e80-39fd-4a79-ba97-48ca87a3f5c5"
}

异常返回示例

{
 "code":2062,
 "id":"4fa207ca-fffd-48bb-94b8-e6f7ca6c99c3",
 "localizedMsg":"请求错误",
 "message":"identityId not exist"
}

错误码

请参考公共错误码

统计用户的消息记录数量

定义描述

path
版本
描述
是否需要用户身份的鉴权
/message/center/record/messagetype/count
1.0.6
统计当前用户的消息记录数量
是，客户端SDK需启用身份的鉴权

请求参数

字段名
子键
类型
是否必填
备注
requestDTO
Map
startCreateTime
Date
N
查询开始时间
endCreateTime
Date
N
查询结束时间
messageType
String
N
不传则三种都查
type
String
Y
MESSAGE: 透传消息
NOTICE:通知消息
参考文末备注[1]
maxId
Long
N
查询条件：id <maxId
minId
Long
N
查询条件: id >minId
isRead
Integer
N
0: 未读
1：已读
eventId
String
N
告警事件ID（由拉取设备对应的告警配置列表接口可以获得）
iotId
String
N
设备ID

返回参数

字段名
类型
描述
data
Map<String, Long>
k: device：设备 announcement：通知 share：分享
v:数量

示例

请求示例

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.1",
        "iotToken": "token"
    },
    "params": {
        "requestDTO": {
            "type": "NOTICE"
        }
    }
}

正常返回示例

{
    "code": 200,
    "data": {
        "share": 6,
        "device": 0,
        "announcement": 0
    },
    "message": "success"
}

错误码

请参考公共错误码

查询用户的消息记录

定义描述

path
版本
描述
是否需要用户身份的鉴权
/message/center/record/query
1.0.6
查询当前用户的消息记录
是，客户端SDK需启用身份的鉴权

请求参数

字段名
子键
类型
是否必填
备注
requestDTO
Map
startCreateTime
Date
N
查询开始时间
endCreateTime
Date
N
查询结束时间
messageType
String
N
device：设备
announcement：通知
share：分享
type
String
Y
MESSAGE: 透传消息 NOTICE:通知消息 参考文末备注[1]
maxId
Long
N
查询条件：id <maxId
minId
Long
N
查询条件: id >minId
pageNo
Integer
Y
pageSize
Integer
Y
最大100
isRead
Integer
N
0:未读
1：已读
sortType
Integer
N
null or 0: gmtCreate倒排
1: gmtCreate正排
iotId
String
N
设备的id：从 1.0.6 起开放

返回参数

字段名
子键
二级子键
三级子键
三级子键
类型
描述
data
Map
count
Long
总数
data
id
List<Map>
gmtCreate
Date
创建时间
gmtModified
Date
修改时间
appKey
Long
title
String
body
String
messageType
String
消息类型
设备、共享、通知
isRead
Integer
阅读状态
extData
Map
附加信息
device
Map
设备信息
iotId
String
设备id
productKey
String
产品key
productName
String
产品名称
icon
String
图标
nickName
String
昵称

示例

请求示例

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.1",
        "iotToken": "token"
    },
    "params": {
        "requestDTO": {
            "type": "NOTICE",
            "pageNo": 1,
            "pageSize": 20
        }
    }
}

正常返回示例

{
    "code": 200,
    "data": {
        "count": 102,
        "data": [{
            "appKey": 1234567,
            "body": "温度高",
            "deviceType": "iOS",
            "extData": {
                "device": {
                    "categoryId": 100,
                    "iotId": "iotId1",
                    "productKey": "p1",
                    "productName": "1"
                }
            },
            "gmtCreate": 1525351832000,
            "gmtModified": 1525351851000,
            "id": 1000000000000200439,
            "isRead": 1,
            "messageId": "-1",
            "messageType": "device",
            "scopeId": "scopeId1",
            "target": "ACCOUNT",
            "targetValue": "userId",
            "tenantId": "tenantId",
            "title": "测试",
            "type": "NOTICE"
        }],
        "queryPageNo": 1,
        "queryPageSize": 10
    },
    "message": "success"
}

错误码

请参考公共错误码

逻辑删除用户的消息记录

定义描述

path
版本
描述
是否需要用户身份的鉴权
/message/center/record/delete
1.0.6
逻辑删除当前用户的消息记录
是，客户端SDK需启用身份的鉴权

请求参数

字段名
子键
类型
是否必填
备注
requestDTO
Map
type
String
Y
MESSAGE: 透传消息 NOTICE:通知消息 参考文末备注[1]
messageType
String
N
id
Long
N
消息记录id
maxId
Long
N
查询条件：id <maxId
minId
Long
N
查询条件: id >minId

注意: messageType, id, maxId, minId 不能同时不填（至少要传一个）

返回参数

字段名 类型 描述
data Integer 删除的记录数量

示例

请求示例

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.1",
        "iotToken": "token"
    },
    "params": {
        "requestDTO": {
            "type": "NOTICE"
        }
    }
}

正常返回示例

{
    "code": 200,
    "data": 10,
    "message": "success"
}

错误码

请参考公共错误码

物理删除用户的消息记录

定义描述

path
版本
描述
是否需要用户的身份鉴权
/message/center/record/delete/physical
1.0.6
物理删除当前用户的消息记录
是，客户端SDK需启用身份的鉴权

请求参数

字段名
子键
类型
是否必填
备注
requestDTO
Map
type
String
Y
MESSAGE: 透传消息 NOTICE:通知消息 参考文末备注[1]
messageType
String
N
id
Long
N
消息记录id
maxId
Long
N
查询条件：id <maxId
minId
Long
N
查询条件: id >minId

返回参数

字段名 类型 描述
data Integer 删除的记录数量

示例

请求示例

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.1",
        "iotToken": "token"
    },
    "params": {
        "requestDTO": {
            "type": "NOTICE"
        }
    }
}

正常返回示例

{
    "code": 200,
    "data": 10,
    "message": "success"
}

错误码

请参考公共错误码

更新用户的消息记录

定义描述

path
版本
描述
是否需要用户身份的鉴权
/message/center/record/modify
1.0.6
更新当前用户的消息记录
目前仅支持更新只读状态
是，客户端SDK需启用身份的鉴权

请求参数

字段名
子键
类型
是否必填
备注
requestDTO
Map
id
Long
N
消息记录id
type
String
Y
MESSAGE: 透传消息 NOTICE:通知消息 参考文末备注[1]
messageType
String
N
maxId
Long
N
查询条件：id <maxId
minId
Long
N
查询条件: id >minId
i​sRead
I​nteger
N​
需要​更新的阅读状态
0​：未读
1：已读

返回参数

字段名 类型 描述
data Integer 更新的记录数量

示例

请求示例

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.1",
        "iotToken": "token"
    },
    "params": {
        "requestDTO": {
            "type": "NOTICE"
        }
    }
}

正常返回示例

{
    "code": 200,
    "data": 5,
    "message": "success"
}

错误码

请参考公共错误码

拉取设备对应的告警配置列表

定义描述

path 版本 描述 是否需要用户身份的鉴权
/message/center/device/notice/list 1.0.5 拉取指定设备对应的告警提醒配置列表（只有配置为进行app应用推送的告警信息才会被获取到) 是，客户端SDK需启用身份的鉴权

请求参数

参数 类型 必填 描述
iotId String 是 设备ID

返回参数

参数 类型 必有 描述
alarmNotices List 否 告警提醒配置列表

alarmNotices列表结构

参数
类型
必填
描述
eventId
String
是
告警事件ID
eventName
String
是
告警事件名称
noticeEnabled
Boolean
是
消息推送提醒开关
true：开启
false: 关闭
如果用户之前从未配置过告警提醒配置，则默认返回true；

示例

请求示例

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.5",
      "iotToken": "token"
    },
    "params": {
        "iotId" : "ChFrkX2CEx6DO88EHXNH0010803d10"
    }
}

正常返回示例

{
    "code": 200,
    "message": "",
    "data": [
       {
           "eventId" : "18012",
           "eventName": "开门提醒",
           "noticeEnabled" : true
       },
       {
           "eventId" : "18013",
           "eventName": "劫持报警",
           "noticeEnabled" : false
       }
    ]
}

错误码

请参考公共错误码

拉取设备告警全局提醒配置-不推荐使用

该接口返回的值已不具备实际意义，请使用/message/center/device/notice/list接口获取每条告警提醒的配置情况；

定义描述

path 版本 描述 是否需要用户身份的鉴权
/message/center/device/global/notice/get 1.0.5 拉取指定设备的全局提醒配置 是，客户端SDK需启用身份的鉴权

请求参数

参数 类型 必填 描述
iotId String 是 设备ID

返回参数

参数
类型
必有
描述
data
Boolean
是
消息推送提醒开关
true：开启
false: 关闭

示例

请求示例

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.5",
      "iotToken": "token"
    },
    "params": {
        "iotId" : "ChFrkX2CEx6DO88EHXNH0010803d10"
    }
}

正常返回示例

{
    "code": 200,
    "message": "success",
    "data": true
}

错误码

请参考公共错误码

设置设备告警提醒配置

定义描述

path 版本 描述 是否需要用户身份的鉴权
/message/center/device/notice/set 1.0.5 配置指定设备的某个告警提醒的开关；无论当前登录用户是设备管理员还是非管理员，该接口仅对用户自身生效 是，客户端SDK需启用身份的鉴权

请求参数

参数
类型
必填
描述
iotId
String
是
设备ID
eventId
String
是
告警事件ID
noticeEnabled
Boolean
是
消息推送提醒开关
true：开启
false: 关闭

返回参数

无业务参数返回

示例

请求示例

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.5",
      "iotToken": "token"
    },
    "params": {
        "iotId" : "ChFrkX2CEx6DO88EHXNH0010803d10",
        "eventId" : "18012",
        "noticeEnabled" : false
    }
}

正常返回示例

{
    "code": 200,
    "message": "success",
    "data": null
}

错误码

请参考公共错误码

设置设备全量告警的提醒配置

定义描述

path
版本
描述
是否需要用户身份的鉴权
/message/center/device/global/notice/set
1.0.5
设置指定设备上的所有告警提醒条目的状态；
例如，一个设备上共有10条告警提醒，如果调用本接口传入true/false，则所有的10条告警提醒都会被设置为true/false
另外，该全量设置不会覆盖到未来新增的告警配置，即假如在此处设置了false后，如果产品所有者在后台又新增了一条告警，则对应的提醒配置默认仍为true；
是，客户端SDK需启用身份的鉴权

请求参数

参数
类型
必填
描述
iotId
String
是
设备ID
noticeEnabled
Boolean
是
消息推送提醒开关
true：开启
false: 关闭

返回参数

无业务参数返回

示例

请求示例

{
    "id": "1509086454180",
    "version": "1.0",
    "request": {
        "apiVer": "1.0.5",
      "iotToken": "token"
    },
    "params": {
        "iotId" : "ChFrkX2CEx6DO88EHXNH0010803d10",
        "noticeEnabled" : false
    }
}

正常返回示例

{
    "code": 200,
    "message": "success",
    "data": null
}

错误码

请参考公共错误码

备注[1]：

MESSAGE类型的消息只可以通过接口查询到；而NOTICE类型的消息，除了可以提供接口查询，还会主动通过手机的推送通道Push给用户（前提是用户APP中使用了飞燕提供的消息推送的SDK）

备注[2]：

关于App角标（app图标右上角未读消息计数小红点）的处理，不同的操作系统平台实现方案差异是比较大；对于Android平台，早期官方对该场景并没有统一的定义和接口，都是由各大ROM厂商自行实现；从Android6.0开始，官方有了统一的接口定义（类似于iOS），但是实际上受限于手机厂商的定制化ROM，用户手机上是否能够支持也是无法保证的；所以当前智能生活平台暂不提供Android平台上的角标处理方案，需要开发者调用消息查询等相关接口自行实现；

对于iOS平台，如果APP处于前台或者处于后台但是仍在运行，此时开发者可以自行处理角标问题；如果APP已经被操作系统Kill的情况下，智能生活平台基于阿里云的移动Push服务，按照iOS官方规范，在APNS通道的消息中增加badge字段，辅助用户处理APP角标；具体使用方式如下：

1、默认情况下，云端不会在消息中包含badge字段，如果开发者需要云端推送该字段，则当前需要提工单进行申请开启，申请时需要提供appkey，并且仅针对该appkey生效；

2、对于清理或修改角标（badge）的计数，则需要调用消息推送SDK中的syncBadgeNum接口，将想要设置的值同步给服务器；具体API使用请参考文档：https://help.aliyun.com/document_detail/42668.html 中的“1.7 角标API”的相关说明；

results matching ""

    No results matching ""