开发者中心
首页
文档
社区
工具
第三方应用开发
快速入门 服务端API 客户端API 运营规范 附录 更新日志 联系我们
第三方应用开发 服务端API 效率工具 日程 日程接口
日程接口

目录

  • 创建日程
  • 更新日程
  • 获取日程详情
  • 取消日程
  • 获取日历下的日程列表
  • 新增日程参与者
  • 删除日程参与者

    • 创建日程

    该接口用于在日历中创建一个日程。

    请求方式： POST（HTTPS）
    请求地址： https://qyapi.weixin.qq.com/cgi-bin/oa/schedule/add?access_token=ACCESS_TOKEN

    请求包体：

    {
	"schedule": {
		"organizer": "userid1",
		"start_time": 1571274600,
		"end_time": 1571320210,
		"attendees": [{
			"userid": "userid2"
		}],
		"summary": "需求评审会议",
		"description": "2.0版本需求初步评审",
		"reminders": {
			"is_remind": 1,
			"remind_before_event_secs": 3600,
			"is_repeat": 1,
			"repeat_type": 7,
			"repeat_until": 1606976813,
			"is_custom_repeat": 1,
			"repeat_interval": 1,
			"repeat_day_of_week": [3, 7],
			"repeat_day_of_month": [10, 21],
			"timezone" : 8
		},
		"location": "广州国际媒体港10楼1005会议室",
		"cal_id": "wcjgewCwAAqeJcPI1d8Pwbjt7nttzAAA"
	},
	"agentid": 1000014
}

    参数说明：

     

    参数必须类型说明
    access_token是string调用接口凭证
    schedule是obj日程信息
    schedule.attendees否obj[]日程参与者列表。最多支持2000人
    schedule.attendees.userid是string日程参与者ID
    不多于64字节
    schedule.summary否string日程标题。0 ~ 128 字符。不填会默认显示为“新建事件”
    schedule.description否string日程描述
    不多于512个字符
    schedule.reminders否obj提醒相关信息
    schedule.reminders.is_remind否int32是否需要提醒。0-否；1-是
    schedule.reminders.is_repeat否int32是否重复日程。0-否；1-是
    schedule.reminders.remind_before_event_secs否uint32日程开始（start_time）前多少秒提醒，当is_remind为1时有效。
    例如： 300表示日程开始前5分钟提醒。目前仅支持以下数值：
    0 - 事件开始时
    300 - 事件开始前5分钟
    900 - 事件开始前15分钟
    3600 - 事件开始前1小时
    86400 - 事件开始前1天
    schedule.reminders.repeat_type否uint32重复类型，当is_repeat为1时有效。目前支持如下类型：
    0 - 每日
    1 - 每周
    2 - 每月
    5 - 每年
    7 - 工作日
    schedule.reminders.repeat_until否uint32重复结束时刻，Unix时间戳。不填或填0表示一直重复
    schedule.reminders.is_custom_repeat否uint32是否自定义重复。0-否；1-是
    schedule.reminders.repeat_interval否uint32重复间隔
    仅当指定为自定义重复时有效
    该字段随repeat_type不同而含义不同
    例如：
    repeat_interval指定为3，repeat_type指定为每周重复，那么每3周重复一次；
    repeat_interval指定为3，repeat_type指定为每月重复，那么每3个月重复一次
    schedule.reminders.repeat_day_of_week否uint32[]每周周几重复
    仅当指定为自定义重复且重复类型为每周时有效
    取值范围：1 ~ 7，分别表示周一至周日
    schedule.reminders.repeat_day_of_month否uint32[]每月哪几天重复
    仅当指定为自定义重复且重复类型为每月时有效
    取值范围：1 ~ 31，分别表示1~31号
    schedule.reminders.timezone否uint32时区。UTC偏移量表示(即偏离零时区的小时数)，东区为正数，西区为负数。
    例如：+8 表示北京时间东八区
    默认为北京时间东八区
    取值范围：-12 ~ +12
    schedule.location否string日程地址
    不多于128个字符
    schedule.organizer是string组织者
    不多于64字节
    schedule.start_time是uint32日程开始时间，Unix时间戳
    schedule.end_time是uint32日程结束时间，Unix时间戳
    schedule.cal_id否string日程所属日历ID。该日历必须是access_token所对应应用所创建的日历。
    注意，这个日历必须是属于组织者(organizer)的日历；
    如果不填，那么插入到组织者的默认日历上。
    第三方应用必须指定cal_id
    不多于64字节
    schedule.allow_active_join否bool是否允许非参与人主动加入日程，默认为开启。
    agentid否uint32授权方安装的应用agentid。仅旧的第三方多应用套件需要填此参数

     

    关于自定义重复的说明：
    is_custom_repeat 如果为0，那么系统会根据 start_time 和 repeat_type 来自动计算下一次重复的时间，例如：

    start_time 为本周周三8点整，repeat_type 为每周重复，那么每周三8点整重复；
    start_time 为本月3号10点整，repeat_type 为每月重复，那么每月3号10点整重复；

    如果 is_custom_repeat 指定为1，那么可以配合 repeat_day_of_week 或 repeat_day_of_month 特别指定周几或几号重复，且可以使用 repeat_interval 指定重复间隔

    返回结果： 

    { 
	"errcode": 0,
	"errmsg" : "ok",
	"schedule_id":"17c7d2bd9f20d652840f72f59e796AAA"
}

    参数说明：

    参数类型说明
    errcodeint32返回码
    errmsgstring错误码描述
    schedule_idstring日程ID

    更新日程

    该接口用于在日历中更新指定的日程。

    注意，更新操作是覆盖式，而不是增量式
    不可更新组织者和日程所属日历ID

    请求方式： POST（HTTPS）
    请求地址： https://qyapi.weixin.qq.com/cgi-bin/oa/schedule/update?access_token=ACCESS_TOKEN

    请求包体：

    {
	"schedule": {
		"organizer": "userid1",
		"schedule_id": "17c7d2bd9f20d652840f72f59e796AAA",
		"start_time": 1571274600,
		"end_time": 1571320210,
		"attendees": [
			{
				"userid": "userid2"
			}
		],
		"summary": "test_summary",
		"description": "test_description",
		"reminders": {
			"is_remind": 1,
			"remind_before_event_secs": 3600,
			"is_repeat": 1,
			"repeat_type": 7,
			"repeat_until": 1606976813,
			"is_custom_repeat": 1,
			"repeat_interval": 1,
			"repeat_day_of_week": [3, 7],
			"repeat_day_of_month": [10, 21],
			"timezone" : 8
		},
		"location": "test_place",
		"skip_attendees ":false
	}
}

    参数说明：

    参数必须类型说明
    access_token是string调用接口凭证
    schedule是obj日程信息
    schedule.schedule_id是string日程ID。创建日程时返回的ID
    schedule.attendees否obj[]日程参与者列表。最多支持2000人
    schedule.attendees.userid是string日程参与者ID
    不多于64字节
    schedule.summary否string日程标题。0 ~ 128 字符。不填会默认显示为“新建事件”
    schedule.description否string日程描述
    不多于512个字符
    schedule.reminders否obj提醒相关信息
    schedule.reminders.is_remind否int32是否需要提醒。0-否；1-是
    schedule.reminders.is_repeat否int32是否重复日程。0-否；1-是
    schedule.reminders.remind_before_event_secs否uint32日程开始（start_time）前多少秒提醒，当is_remind为1时有效。
    例如： 300表示日程开始前5分钟提醒。目前仅支持以下数值：
    0 - 事件开始时
    300 - 事件开始前5分钟
    900 - 事件开始前15分钟
    3600 - 事件开始前1小时
    86400 - 事件开始前1天
    schedule.reminders.repeat_type否uint32重复类型，当is_repeat为1时有效。目前支持如下类型：
    0 - 每日
    1 - 每周
    2 - 每月
    5 - 每年
    7 - 工作日
    schedule.reminders.repeat_until否uint32重复结束时刻，Unix时间戳。不填或填0表示一直重复
    schedule.reminders.is_custom_repeat否uint32是否自定义重复。0-否；1-是
    schedule.reminders.repeat_interval否uint32重复间隔
    仅当指定为自定义重复时有效
    该字段随repeat_type不同而含义不同
    例如：
    repeat_interval指定为2，repeat_type指定为每周重复，那么每2周重复一次；
    repeat_interval指定为2，repeat_type指定为每月重复，那么每2月重复一次
    schedule.reminders.repeat_day_of_week否uint32[]每周周几重复
    仅当指定为自定义重复且重复类型为每周时有效
    取值范围：1 ~ 7，分别表示周一至周日
    schedule.reminders.repeat_day_of_month否uint32[]每月哪几天重复
    仅当指定为自定义重复且重复类型为每月时有效
    取值范围：1 ~ 31，分别表示1~31号
    schedule.reminders.timezone否uint32时区。UTC偏移量表示(即偏离零时区的小时数)，东区为正数，西区为负数。
    例如：+8 表示北京时间东八区
    默认为北京时间东八区
    取值范围：-12 ~ +12
    schedule.location否string日程地址
    不多于128个字符
    schedule.organizer否string组织者
    不多于64字节
    schedule.start_time是uint32日程开始时间，Unix时间戳
    schedule.end_time是uint32日程结束时间，Unix时间戳
    schedule.skip_attendees否bool忽略掉attendees参数，只更新其他参数,默认值是false

    关于自定义重复的说明：
    is_custom_repeat 如果为0，那么系统会根据 start_time 和 repeat_type 来自动计算下一次重复的时间，例如：

    start_time 为本周周三8点整，repeat_type 为每周重复，那么每周三8点整重复；
    start_time 为本月3号10点整，repeat_type 为每月重复，那么每月3号10点整重复；

    如果 is_custom_repeat 指定为1，那么可以配合 repeat_day_of_week 或 repeat_day_of_month 特别指定周几或几号重复，且可以使用 repeat_interval 指定重复间隔

     

    返回结果： 

    {
	"errcode": 0,
	"errmsg" : "ok"
}

    参数说明：

    参数类型说明
    errcodeint32返回码
    errmsgstring错误码描述

    获取日程详情

    该接口用于获取指定的日程详情。

    请求方式： POST（HTTPS）
    请求地址： https://qyapi.weixin.qq.com/cgi-bin/oa/schedule/get?access_token=ACCESS_TOKEN

    请求包体：

    {
	"schedule_id_list": [
		"17c7d2bd9f20d652840f72f59e796AAA"
	]
}

    参数说明：

    参数是否必须说明
    schedule_id_list是日程ID列表。一次最多拉取1000条

     

    返回结果： 

    {
	"errcode": 0,
	"errmsg": "ok",
	"schedule_list": [{
		"schedule_id": "17c7d2bd9f20d652840f72f59e796AAA",
		"organizer": "userid1",
		"attendees": [{
			"userid": "userid2",
			"response_status": 1
		}],
		"summary": "test_summary",
		"description": "test_content",
		"reminders": {
			"is_remind": 1,
			"is_repeat": 1,
			"remind_before_event_secs": 3600,
			"remind_time_diffs": [
				-3600
			],
			"repeat_type": 7,
			"repeat_until": 1606976813,
			"is_custom_repeat": 1,
			"repeat_interval": 1,
			"repeat_day_of_week": [3, 7],
			"repeat_day_of_month": [10, 21],
			"timezone" : 8,
			"exclude_time_list": [
				{
					"start_time": 1571361000
				}
			]
		},
		"location": "test_place",
		"cal_id": "wcjgewCwAAqeJcPI1d8Pwbjt7nttzAAA",
		"start_time": 1571274600,
		"end_time": 1571579410,
		"status": 1
	}]
}

    参数说明：

    参数类型说明
    errcodeint32返回码
    errmsgstring错误码描述
    schedule_listobj[]日程列表
    schedule_list.schedule_idstring日程ID
    schedule_list.attendeesobj[]日程参与者列表。最多支持2000人
    schedule_list.attendees.useridstring日程参与者ID
    schedule_list.attendees.response_statusuint32日程参与者的接受状态。
    0 - 未处理
    1 - 待定
    2 - 全部接受
    3 - 仅接受一次
    4 - 拒绝
    schedule_list.summarystring日程标题
    schedule_list.descriptionstring日程描述
    schedule_list.remindersobj提醒相关信息
    schedule_list.reminders.is_remindint32是否需要提醒。0-否；1-是
    schedule_list.reminders.is_repeatint32是否重复日程。0-否；1-是
    schedule_list.reminders.remind_before_event_secsuint32日程开始（start_time）前多少秒提醒，当is_remind为1时有效。例如： 300表示日程开始前5分钟提醒。目前仅支持以下数值：
    0 - 事件开始时
    300 - 事件开始前5分钟
    900 - 事件开始前15分钟
    3600 - 事件开始前1小时
    86400 - 事件开始前1天
    注意：建议使用 remind_time_diffs 字段，该字段后续将会废弃。
    schedule_list.reminders.remind_time_diffsint32[]日程开始（start_time）与提醒时间的差值，当is_remind为1时有效。例如：-300表示日程开始前5分钟提醒。
    特殊情况：企业微信终端设置的“全天”类型的日程，由于start_time是0点时间戳，提醒如果设置了当天9点，则会出现正数32400。
    取值范围：-604800 ~ 86399
    schedule_list.reminders.repeat_typeuint32重复类型，当is_repeat为1时有效。目前支持如下类型：
    0 - 每日
    1 - 每周
    2 - 每月
    5 - 每年
    7 - 工作日
    schedule_list.reminders.repeat_untiluint32重复结束时刻，Unix时间戳。不填或填0表示一直重复
    schedule_list.reminders.is_custom_repeatuint32是否自定义重复。0-否；1-是
    schedule_list.reminders.repeat_intervaluint32重复间隔
    仅当指定为自定义重复时有效
    该字段随repeat_type不同而含义不同
    例如：
    repeat_interval指定为2，repeat_type指定为每周重复，那么每2周重复一次；
    repeat_interval指定为2，repeat_type指定为每月重复，那么每2月重复一次
    schedule_list.reminders.repeat_day_of_weekuint32[]每周周几重复
    仅当指定为自定义重复且重复类型为每周时有效
    取值范围：1 ~ 7，分别表示周一至周日
    schedule_list.reminders.repeat_day_of_monthuint32[]每月哪几天重复
    仅当指定为自定义重复且重复类型为每月时有效
    取值范围：1 ~ 31，分别表示1~31号
    schedule_list.reminders.timezoneuint32时区。UTC偏移量表示(即偏离零时区的小时数)，东区为正数，西区为负数。
    例如：+8 表示北京时间东八区
    默认为北京时间东八区
    取值范围：-12 ~ +12
    schedule_list.reminders.exclude_time_listobj[]重复日程不包含的日期列表。对重复日程修改/删除特定一天或多天，则原来的日程将会排除对应的日期。
    schedule_list.reminders.exclude_time_list.start_timeuint32不包含的日期时间戳。
    schedule_list.locationstring日程地址
    不多于128个字符
    schedule_list.organizerstring组织者
    不多于64字节
    schedule_list.statusuint32日程状态。0-正常；1-已取消
    schedule_list.start_timeuint32日程开始时间，Unix时间戳
    schedule_list.end_timeuint32日程结束时间，Unix时间戳
    schedule_list.cal_idstring日程所属日历ID。该日历必须是access_token所对应应用所创建的日历。
    注意，这个日历必须是属于组织者(organizer)的日历；
    如果不填，那么插入到组织者的默认日历上。
    第三方应用必须指定cal_id
    不多于64字节

     

    注意，被取消的日程也可以拉取详情，调用者需要检查 status

    取消日程

    该接口用于取消指定的日程。

    请求方式： POST（HTTPS）
    请求地址： https://qyapi.weixin.qq.com/cgi-bin/oa/schedule/del?access_token=ACCESS_TOKEN

    请求包体：

    {
	"schedule_id":"17c7d2bd9f20d652840f72f59e796AAA"
}

    参数说明：

    参数是否必须说明
    schedule_id是日程ID

     

    返回结果： 

    { 
	"errcode": 0,
	"errmsg" : "ok"
}

    参数说明：

    参数说明
    errcode错误码
    errmsg错误码说明

    获取日历下的日程列表

    该接口用于获取指定的日历下的日程列表。
    仅可获取应用自己创建的日历下的日程。

    请求方式： POST（HTTPS）
    请求地址： https://qyapi.weixin.qq.com/cgi-bin/oa/schedule/get_by_calendar?access_token=ACCESS_TOKEN

    请求包体：

    {
	"cal_id": "wcjgewCwAAqeJcPI1d8Pwbjt7nttzAAA",
	"offset" : 100,
	"limit" : 1000
}

    参数说明：

    参数是否必须说明
    cal_id是日历ID
    offset否分页，偏移量, 默认为0
    limit否分页，预期请求的数据量，默认为500，取值范围 1 ~ 1000

    当日程较多时，需要使用参数是offset及limit 分页获取，注意offset是以0为起点，这里以图例简单说明：
    page_size/page_index图示说明当获取到的 schedule_list 是空的时候，表示offset已经过大，此时应终止获取。若有新增日程，可在此基础上继续增量获取。

     

    返回结果： 

    {
	"errcode": 0,
	"errmsg": "ok",
	"schedule_list": [{
		"schedule_id": "17c7d2bd9f20d652840f72f59e796AAA",
		"sequence": 100,
		"attendees": [{
			"userid": "userid1",
			"response_status": 0
		}],
		"summary": "test_summary",
		"description": "test_content",
		"reminders": {
			"is_remind": 1,
			"is_repeat": 1,
			"remind_before_event_secs": 3600,
			"repeat_type": 7,
			"repeat_until": 1606976813,
			"is_custom_repeat": 1,
			"repeat_interval": 1,
			"repeat_day_of_week": [3, 7],
			"repeat_day_of_month": [10, 21],
			"timezone" : 8
		},
		"location": "test_place",
		"start_time": 1571274600,
		"end_time": 1571320210,
		"status": 1,
		"cal_id": "wcjgewCwAAqeJcPI1d8Pwbjt7nttzAAA"
	}]
}

    参数说明：

    参数类型说明
    errcodeint32返回码
    errmsgstring错误码描述
    schedule_listobj[]日程列表
    schedule_list.schedule_idstring日程ID
    schedule_list.attendeesobj[]日程参与者列表。最多支持2000人
    schedule_list.attendees.useridstring日程参与者ID
    schedule_list.attendees.response_statusuint32日程参与者的接受状态。
    0 - 未处理
    1 - 待定
    2 - 全部接受
    3 - 仅接受一次
    4 - 拒绝
    schedule_list.summarystring日程标题
    schedule_list.descriptionstring日程描述
    schedule_list.remindersobj提醒相关信息
    schedule_list.reminders.is_remindint32是否需要提醒。0-否；1-是
    schedule_list.reminders.is_repeatint32是否重复日程。0-否；1-是
    schedule_list.reminders.remind_before_event_secsuint32日程开始（start_time）前多少秒提醒，当is_remind为1时有效。例如： 300表示日程开始前5分钟提醒。目前仅支持以下数值：
    0 - 事件开始时
    300 - 事件开始前5分钟
    900 - 事件开始前15分钟
    3600 - 事件开始前1小时
    86400 - 事件开始前1天
    schedule_list.reminders.repeat_typeuint32重复类型，当is_repeat为1时有效。目前支持如下类型：
    0 - 每日
    1 - 每周
    2 - 每月
    5 - 每年
    7 - 工作日
    schedule_list.reminders.repeat_untiluint32重复结束时刻，Unix时间戳。不填或填0表示一直重复
    schedule_list.reminders.is_custom_repeatuint32是否自定义重复。0-否；1-是
    schedule_list.reminders.repeat_intervaluint32重复间隔
    仅当指定为自定义重复时有效
    该字段随repeat_type不同而含义不同
    例如：
    repeat_interval指定为2，repeat_type指定为每周重复，那么每2周重复一次；
    repeat_interval指定为2，repeat_type指定为每月重复，那么每2月重复一次
    schedule_list.reminders.repeat_day_of_weekuint32[]每周周几重复
    仅当指定为自定义重复且重复类型为每周时有效
    取值范围：1 ~ 7，分别表示周一至周日
    schedule_list.reminders.repeat_day_of_monthuint32[]每月哪几天重复
    仅当指定为自定义重复且重复类型为每月时有效
    取值范围：1 ~ 31，分别表示1~31号
    schedule_list.reminders.timezoneuint32时区。UTC偏移量表示(即偏离零时区的小时数)，东区为正数，西区为负数。
    例如：+8 表示北京时间东八区
    默认为北京时间东八区
    取值范围：-12 ~ +12
    schedule_list.locationstring日程地址
    不多于128个字符
    schedule_list.organizerstring组织者
    不多于64字节
    schedule_list.statusuint32日程状态。0-正常；1-已取消
    schedule_list.start_timeuint32日程开始时间，Unix时间戳
    schedule_list.end_timeuint32日程结束时间，Unix时间戳
    schedule_list.sequenceuint64日程编号，是一个自增数字
    schedule_list.cal_idstring日程所属日历ID。该日历必须是access_token所对应应用所创建的日历。
    注意，这个日历必须是属于组织者(organizer)的日历；
    如果不填，那么插入到组织者的默认日历上。
    第三方应用必须指定cal_id
    不多于64字节

    注意，被取消的日程也可以拉取详情，调用者需要检查status

    新增日程参与者

    该接口用于在日历中更新指定的日程参与者列表

    注意，该接口是增量式

    请求方式： POST（HTTPS）
    请求地址： https://qyapi.weixin.qq.com/cgi-bin/oa/schedule/add_attendees?access_token=ACCESS_TOKEN

    请求包体：

    {
	"schedule_id": "17c7d2bd9f20d652840f72f59e796AAA",
	"attendees": [
		{
			"userid": "userid2"
		}
	]
}

    参数说明：

    参数必须类型说明
    access_token是string调用接口凭证
    schedule_id是string日程ID。创建日程时返回的ID
    attendees否obj[]日程参与者列表。累积最多支持2000人
    attendees.userid是string日程参与者ID
    不多于64字节

     

    返回结果：

    {
	"errcode": 0,
	"errmsg" : "ok"
}

    参数说明：

    参数类型说明
    errcodeint32返回码
    errmsgstring错误码描述

    删除日程参与者

    该接口用于在日历中更新指定的日程参与者列表

    注意，该接口是增量式

    请求方式： POST（HTTPS）
    请求地址： https://qyapi.weixin.qq.com/cgi-bin/oa/schedule/del_attendees?access_token=ACCESS_TOKEN

    请求包体：

    {
	"schedule_id": "17c7d2bd9f20d652840f72f59e796AAA",
	"attendees": [
		{
			"userid": "userid2"
		}
	]
}

    参数说明：

    参数必须类型说明
    access_token是string调用接口凭证
    schedule_id是string日程ID。创建日程时返回的ID
    attendees否obj[]日程参与者列表。最多支持2000人
    attendees.userid是string日程参与者ID
    不多于64字节

    返回结果：

    {
	"errcode": 0,
	"errmsg" : "ok"
}

    参数说明：

    参数类型说明
    errcodeint32返回码
    errmsgstring错误码描述
    上一篇
    日历接口
    下一篇
    回调事件