# 获取消息推送概览
目标：查看应用在某一天/某一周/某一个月的机器人消息推送数据，可以根据部门做筛选
**注意事项**：1. 仅支持企业版/旗舰版租户使用
2. 一般每天早上10点产出两天前的数据。
3. 已经支持的指标包括：消息推送给用户的次数、消息触达的人数、消息1小时阅读量、消息12小时阅读量
4. 按照部门查看数据时，会展示当前部门以及其子部门的整体使用情况
5. 调用频控为100次/分
## 请求
基本 |
---|---
HTTP URL | https://open.feishu.cn/open-apis/application/v6/applications/:app_id/app_usage/message_push_overview
HTTP Method | POST
接口频率限制 | [100 次/分钟](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App
权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用** | 获取机器人发送消息的概览数据(application:application.app_message_stats.overview:readonly)
### 请求头
名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer t-7f1bcd13fc57d46bac21793a18e560"
[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
Content-Type | string | 是 | **固定值**："application/json; charset=utf-8"
### 路径参数
名称 | 类型 | 描述
---|---|---
app_id | string | 目标应用ID，支持自建应用
**示例值**："cli_9f115af860f7901b"
### 查询参数
名称 | 类型 | 必填 | 描述
---|---|---|---
department_id_type | string | 否 | 调用中使用的部门ID的类型
**示例值**：open_department_id
**可选值有**：
- department_id：以自定义department_id来标识部门
- open_department_id：以open_department_id来标识部门
**默认值**：`open_department_id`
### 请求体
名称 | 类型 | 必填 | 描述
---|---|---|---
date | string | 是 | 查询日期，若cycle_type为week，则输入的date必须为周一； 若cycle_type为month，则输入的date必须为每月1号
**示例值**："2021-07-08"
cycle_type | int | 是 | 枚举值：day，week，month；week指自然周，返回当前日期所在周的数据；不满一周则从周一到当前日期算。month指自然月，返回当前日期所在月的数据。
**示例值**：1
**可选值有**：
- 1：日活，指自然日，返回当前日期所在日的数据
- 2：周活，指自然周，返回当前日期所在周的数据。若到查询时当周还没结束，则返回周一到当前日期的数值。例如在2021/7/15 查询2021/7/5 这一周的数据，则代表的是2021/7/5 ~ 2021/7/11。但若是在2021/7/8 查询2021/7/5 这一周的数据，则返回的是2021/7/5 ~ 2021/7/7 的数据
- 3：月活，指自然月，返回当前日期所在月的数据。若不满一个月则返回当月1日到截止日期前的数据。例如在2021/8/15 查询 7月的数据，则代表2021/7/1~2021/7/31。 若在2021/8/15 查询8月的数据，则代表2021/8/1~2021/8/14的数据
department_id | string | 否 | 需要查询的部门id，获取方法可参考[部门ID概述](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/department/field-overview)
- 若部门id为空，则返回当前租户的使用数据；若填写部门id，则返回当前部门的使用数据（包含子部门的用户）；
- 若路径参数中department_id_type为空或者为open_department_id，则此处应该填写部门的 open_department_id；若路径参数中department_id_type为department_id，则此处应该填写部门的 department_id。返回当前部门的使用数据； 若不填写，则返回当前租户的使用数据
**示例值**："od-4e6ac4d14bcd5071a37a39de902c7141"
### 请求体示例
```json
{
"cycle_type": "1",
"date": "2021-11-18",
"department_id": "od-bb009b4df5431400dc31d3bc8a37e069"
}
```
## 响应
### 响应体
名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-
items | application.app_usage\[\] | 消息推送情况，指标值包括：send_msg_count：消息推送数、send_user_count：消息触达人数、read_in_1h_count：消息1h阅读量、read_in_12h_count：消息12h阅读量
**注意**：将一条消息推送至群聊，该消息的推送数等于群聊人数。例如群聊内有 5 个人：
- 如果将 1 条消息推送至群聊后，消息推送数（send_msg_count）为 5、消息触达人数（send_user_count）为 5。
- 如果将 2 条消息推送至群聊后，消息推送数（send_msg_count）为 10、消息触达人数（send_user_count）为 5。
metric_name | string | 指标名称
metric_value | int | 指标值
### 响应体示例
```json
{
"code": 0,
"data": {
"items": [
{
"metric_name": "send_msg_count",
"metric_value": 7
},
{
"metric_name": "send_user_count",
"metric_value": 7
},
{
"metric_name": "read_in_1h_count",
"metric_value": 20
},
{
"metric_name": "read_in_12h_count",
"metric_value": 20
}
]
},
"msg": "success"
}
```
### 错误码
HTTP状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
403 | 211004 | no authority for quota limit | 检查是否是企业版/旗舰版租户
403 | 211010 | invalid date range | 检查 date 的取值范围是否正确
404 | 211011 | data not found | 数据不存在。可能是该应用在目标查询日期范围内没有数据。请检查请求参数
400 | 211007 | invalid date format | 检查 date 字段的格式是否符合"2021-07-01"
400 | 211005 | invalid app id | 检查 app id
## 附录-统计指标说明
指标 | 指标定义 | 备注
---|---|---
消息推送数 | - 统计周期内，消息推送给用户的次数。 | - 支持查看某一天/某一周/某一个月的数据
消息触达人数 | - 统计周期内，消息触达的人数 | - 支持查看某一天/某一周/某一个月的数据
消息1h阅读量 | - 统计周期内，sum(某一条消息1h内的已读用户数) | - 支持查看某一天/某一周/某一个月的数据
消息12h阅读量 | - 统计周期内，sum(某一条消息12h内的已读用户数) | - 支持查看某一天/某一周/某一个月的数据