企业内部开发 服务端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_tokenstring调用接口凭证
    scheduleobj日程信息
    schedule.attendeesobj[]日程参与者列表。最多支持2000人
    schedule.attendees.useridstring日程参与者ID
    不多于64字节
    schedule.summarystring日程标题。0 ~ 128 字符。不填会默认显示为“新建事件”
    schedule.descriptionstring日程描述
    不多于512个字符
    schedule.remindersobj提醒相关信息
    schedule.reminders.is_remindint32是否需要提醒。0-否;1-是
    schedule.reminders.is_repeatint32是否重复日程。0-否;1-是
    schedule.reminders.remind_before_event_secsuint32日程开始(start_time)前多少秒提醒,当is_remind为1时有效。
    例如: 300表示日程开始前5分钟提醒。目前仅支持以下数值:
    0 - 事件开始时
    300 - 事件开始前5分钟
    900 - 事件开始前15分钟
    3600 - 事件开始前1小时
    86400 - 事件开始前1天
    schedule.reminders.repeat_typeuint32重复类型,当is_repeat为1时有效。目前支持如下类型:
    0 - 每日
    1 - 每周
    2 - 每月
    5 - 每年
    7 - 工作日
    schedule.reminders.repeat_untiluint32重复结束时刻,Unix时间戳。不填或填0表示一直重复
    schedule.reminders.is_custom_repeatuint32是否自定义重复。0-否;1-是
    schedule.reminders.repeat_intervaluint32重复间隔
    仅当指定为自定义重复时有效
    该字段随repeat_type不同而含义不同
    例如:
    repeat_interval指定为3,repeat_type指定为每周重复,那么每3周重复一次;
    repeat_interval指定为3,repeat_type指定为每月重复,那么每3个月重复一次
    schedule.reminders.repeat_day_of_weekuint32[]每周周几重复
    仅当指定为自定义重复且重复类型为每周时有效
    取值范围:1 ~ 7,分别表示周一至周日
    schedule.reminders.repeat_day_of_monthuint32[]每月哪几天重复
    仅当指定为自定义重复且重复类型为每月时有效
    取值范围:1 ~ 31,分别表示1~31号
    schedule.reminders.timezoneuint32时区。UTC偏移量表示(即偏离零时区的小时数),东区为正数,西区为负数。
    例如:+8 表示北京时间东八区
    默认为北京时间东八区
    取值范围:-12 ~ +12
    schedule.locationstring日程地址
    不多于128个字符
    schedule.organizerstring组织者
    不多于64字节
    schedule.start_timeuint32日程开始时间,Unix时间戳
    schedule.end_timeuint32日程结束时间,Unix时间戳
    schedule.cal_idstring日程所属日历ID。该日历必须是access_token所对应应用所创建的日历。
    注意,这个日历必须是属于组织者(organizer)的日历;
    如果不填,那么插入到组织者的默认日历上。
    第三方应用必须指定cal_id
    不多于64字节
    schedule.allow_active_joinbool是否允许非参与人主动加入日程,默认为开启。
    agentiduint32授权方安装的应用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_tokenstring调用接口凭证
    scheduleobj日程信息
    schedule.schedule_idstring日程ID。创建日程时返回的ID
    schedule.attendeesobj[]日程参与者列表。最多支持2000人
    schedule.attendees.useridstring日程参与者ID
    不多于64字节
    schedule.summarystring日程标题。0 ~ 128 字符。不填会默认显示为“新建事件”
    schedule.descriptionstring日程描述
    不多于512个字符
    schedule.remindersobj提醒相关信息
    schedule.reminders.is_remindint32是否需要提醒。0-否;1-是
    schedule.reminders.is_repeatint32是否重复日程。0-否;1-是
    schedule.reminders.remind_before_event_secsuint32日程开始(start_time)前多少秒提醒,当is_remind为1时有效。
    例如: 300表示日程开始前5分钟提醒。目前仅支持以下数值:
    0 - 事件开始时
    300 - 事件开始前5分钟
    900 - 事件开始前15分钟
    3600 - 事件开始前1小时
    86400 - 事件开始前1天
    schedule.reminders.repeat_typeuint32重复类型,当is_repeat为1时有效。目前支持如下类型:
    0 - 每日
    1 - 每周
    2 - 每月
    5 - 每年
    7 - 工作日
    schedule.reminders.repeat_untiluint32重复结束时刻,Unix时间戳。不填或填0表示一直重复
    schedule.reminders.is_custom_repeatuint32是否自定义重复。0-否;1-是
    schedule.reminders.repeat_intervaluint32重复间隔
    仅当指定为自定义重复时有效
    该字段随repeat_type不同而含义不同
    例如:
    repeat_interval指定为2,repeat_type指定为每周重复,那么每2周重复一次;
    repeat_interval指定为2,repeat_type指定为每月重复,那么每2月重复一次
    schedule.reminders.repeat_day_of_weekuint32[]每周周几重复
    仅当指定为自定义重复且重复类型为每周时有效
    取值范围:1 ~ 7,分别表示周一至周日
    schedule.reminders.repeat_day_of_monthuint32[]每月哪几天重复
    仅当指定为自定义重复且重复类型为每月时有效
    取值范围:1 ~ 31,分别表示1~31号
    schedule.reminders.timezoneuint32时区。UTC偏移量表示(即偏离零时区的小时数),东区为正数,西区为负数。
    例如:+8 表示北京时间东八区
    默认为北京时间东八区
    取值范围:-12 ~ +12
    schedule.locationstring日程地址
    不多于128个字符
    schedule.organizerstring组织者
    不多于64字节
    schedule.start_timeuint32日程开始时间,Unix时间戳
    schedule.end_timeuint32日程结束时间,Unix时间戳
    schedule.skip_attendeesbool忽略掉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

    当日程较多时,需要使用参数是offsetlimit 分页获取,注意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_tokenstring调用接口凭证
    schedule_idstring日程ID。创建日程时返回的ID
    attendeesobj[]日程参与者列表。累积最多支持2000人
    attendees.useridstring日程参与者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_tokenstring调用接口凭证
    schedule_idstring日程ID。创建日程时返回的ID
    attendeesobj[]日程参与者列表。最多支持2000人
    attendees.useridstring日程参与者ID
    不多于64字节

    返回结果:

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

    参数说明:

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