飞书开放平台 Server API 文档

主题

创建任务 ​

该接口可以创建一个任务，支持填写任务的基本信息，包括任务的标题，描述及协作者等。 在此基础上，创建任务时可以设置截止时间和重复规则，将任务设置为定期执行的重复任务。通过添加协作者，则可以让其他用户协同完成该任务。 此外，接口也提供了一些支持自定义内容的字段，调用方可以实现定制化效果，如完成任务后跳转到指定结束界面。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/task/v1/tasks
HTTP MethodPOST
接口频率限制100 次/分钟
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用task:task 查看、创建、编辑和删除任务（旧版）
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 contact:user.employee_id:readonly 获取用户 user ID

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Typestring是固定值："application/json; charset=utf-8"

查询参数 ​

名称类型必填描述
user_id_typestring否用户 ID 类型
示例值：open_id
可选值有：
- open_id: 标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。了解更多：如何获取 Open ID - union_id: 标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。了解更多：如何获取 Union ID？ - user_id: 标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。了解更多：如何获取 User ID？
默认值：open_id
当值为 user_id，字段权限要求： contact:user.employee_id:readonly 获取用户 user ID

请求体 ​

名称类型必填描述
summarystring否任务的标题，类型为文本字符串。 如果要在任务标题中插入 URL 或者 @某个用户，请使用rich_summary字段。 创建任务时，任务标题(summary字段)和任务富文本标题(rich_summary字段)不能同时为空，需要至少填充其中一个字段。
> Info: 任务标题和任务富文本标题同时存在时只使用富文本标题。
示例值："完成本季度OKR编写"
数据校验规则：
- 长度范围：0 ～ 1000 字符
descriptionstring否任务的描述，类型为文本字符串。 如果要在任务描述中插入 URL 或者 @某个用户，请使用rich_description字段。
> Info: 任务备注和任务富文本备注同时存在时只使用富文本备注。
示例值："对本次会议内容复盘总结，编写更新本季度OKR"
数据校验规则：
- 长度范围：0 ～ 65536 字符
extrastring否附属信息。 接入方可以传入base64 编码后的自定义的数据。用户如果需要对当前任务备注信息，但对外不显示，可使用该字段进行存储。 该数据会在获取任务详情时，原样返回给用户。
示例值："dGVzdA=="
数据校验规则：
- 长度范围：0 ～ 65536 字符
duedue否任务的截止时间设置
  └ timestring否表示截止时间的Unix时间戳（单位为秒）。
示例值："1623124318"
  └ timezonestring否截止时间对应的时区。 传入值需要符合IANA Time Zone Database标准，规范见Time Zone Database。
示例值："Asia/Shanghai"
默认值：Asia/Shanghai
  └ is_all_dayboolean否标记任务是否为全天任务。 包括如下取值： - true：表示是全天任务，全天任务的截止时间为当天 UTC 时间的 0 点。 - false：表示不是全天任务。
示例值：false
默认值：false
originorigin是任务关联的第三方平台来源信息
  └ platform_i18n_namestring是任务来源的名称。 用于在任务中心详情页展示。需要提供一个字典，支持多种语言名称映射。应用在使用不同语言时，导入来源也将展示对应的内容。详细参见：任务字段补充说明
示例值："{\"zh_cn\": \"IT 工作台\", \"en_us\": \"IT Workspace\"}"
数据校验规则：
- 长度范围：0 ～ 1024 字符
  └ hrefhref否任务关联的来源平台详情页链接
    └ urlstring否具体链接地址。 URL仅支持解析http、https。详细参见：任务字段补充说明
示例值："https://support.feishu.com/internal/foo-bar"
数据校验规则：
- 长度范围：0 ～ 1024 字符
    └ titlestring否链接对应的标题
示例值："反馈一个问题，需要协助排查"
数据校验规则：
- 长度范围：0 ～ 512 字符
can_editboolean否此字段用于控制该任务在飞书任务中心是否可编辑，默认为false
> Info: 已经废弃，向前兼容故仍然保留，但不推荐使用
示例值：true
默认值：false
customstring否自定义完成配置。 此字段用于设置完成任务时的页面跳转，或展示提示语。详细参见：任务字段补充说明
示例值："{"custom_complete":{"android":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}},"ios":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}},"pc":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}}}}"
数据校验规则：
- 长度范围：0 ～ 65536 字符
collaborator_idsstring\[\]否创建任务时添加的执行者用户id列表。 传入的值为 user_id 或 open_id ，由user_id_type 决定。user_id和open_id的获取可见文档：如何获取不同的用户 ID。
示例值：["ou_49dadcd6fd55da971d887087c4f3a37a"]
数据校验规则：
- 最大长度：100
follower_idsstring\[\]否创建任务时添加的关注者用户id列表。 传入的值为 user_id 或 open_id ，由user_id_type 决定。user_id和open_id的获取可见文档：如何获取不同的用户 ID。
示例值：["ou_49dadcd6fd55da971d887087c4f3a37a"]
数据校验规则：
- 最大长度：100
repeat_rulestring否重复任务的规则表达式。 语法格式参见RRule语法规范 4.3.10小节
示例值："FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR"
rich_summarystring否富文本任务标题。语法格式参见Markdown模块 。创建任务时，任务标题(summary字段)和任务富文本标题(rich_summary字段)不能同时为空，需要至少填充其中一个字段。
示例值："完成本季度OKR编写[飞书开放平台](https://open.feishu.cn/)"
数据校验规则：
- 长度范围：0 ～ 1000 字符
rich_descriptionstring否富文本任务备注。语法格式参见Markdown模块
示例值："对本次会议内容复盘总结，编写更新本季度OKR[飞书开放平台](https://open.feishu.cn/)"
数据校验规则：
- 长度范围：0 ～ 65536 字符

请求体示例 ​

json
{
    "summary": "每天喝八杯水，保持身心愉悦",
    "description": "多吃水果，多运动，健康生活，快乐工作。",
    "rich_summary": "富文本标题[飞书开放平台](https://open.feishu.cn)",
    "rich_description": "富文本备注[飞书开放平台](https://open.feishu.cn)",
    "extra": "dGVzdA==",
    "due": {
        "time": "1623124318",
        "timezone": "Asia/Shanghai",
        "is_all_day": false
    },
    "origin": {
        "platform_i18n_name": "{\"zh_cn\": \"IT 工作台\", \"en_us\": \"IT Workspace\"}",
        "href": {
            "url": "https://support.feishu.com/internal/foo-bar",
            "title": "反馈一个问题，需要协助排查"
        }
    },
    "can_edit":true,
    "custom": "{\"custom_complete\":{\"android\":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}},\"ios\":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}},\"pc\":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}}}}",
    "follower_ids": ["ou_13585843f02bc94923ed17a007cbc9b1", "ou_219a0611de2a639aa939ee97013f37a5"],
    "collaborator_ids": ["ou_13585843f02bc94923ed17a007cbc9b1", "ou_219a0611de2a639aa939ee97013f37a5"],
    "repeat_rule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR"
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ tasktask返回创建好的任务
    └ idstring任务的唯一ID，例如"83912691-2e43-47fc-94a4-d512e03984fa"
    └ summarystring任务的标题，类型为文本字符串。 如果要在任务标题中插入 URL 或者 @某个用户，请使用rich_summary字段。 创建任务时，任务标题(summary字段)和任务富文本标题(rich_summary字段)不能同时为空，需要至少填充其中一个字段。
> Info: 任务标题和任务富文本标题同时存在时只使用富文本标题。
    └ descriptionstring任务的描述，类型为文本字符串。 如果要在任务描述中插入 URL 或者 @某个用户，请使用rich_description字段。
> Info: 任务备注和任务富文本备注同时存在时只使用富文本备注。
    └ complete_timestring任务的完成时间戳（单位为秒），完成时间为0则表示任务尚未完成。 不支持部分完成，只有整个任务完成，该字段才会有非0值。
    └ creator_idstring任务的创建者 ID。 其中查询字段 user_id_type 是用于控制返回体中 creator_id 的类型，不传时默认返回 open_id。 特别的，使用tenant_access_token 调用接口时，如果是user_id_type是openid，则返回代表该应用身份的openid；当user_id_type为user_id时，不返回creator_id。原因是user_id代表一个真实飞书用户的id，应用身份没有user_id。使用user_access_token调用接口正常返回创建者。
    └ extrastring附属信息。 接入方可以传入base64 编码后的自定义的数据。用户如果需要对当前任务备注信息，但对外不显示，可使用该字段进行存储。 该数据会在获取任务详情时，原样返回给用户。
    └ create_timestring任务的创建时间的Unix时间戳（单位为秒）
    └ update_timestring任务的更新时间的Unix时间戳（单位为秒） 创建任务时update_time与create_time相同
    └ duedue任务的截止时间设置
      └ timestring表示截止时间的Unix时间戳（单位为秒）。
      └ timezonestring截止时间对应的时区。 传入值需要符合IANA Time Zone Database标准，规范见Time Zone Database。
      └ is_all_dayboolean标记任务是否为全天任务。 包括如下取值： - true：表示是全天任务，全天任务的截止时间为当天 UTC 时间的 0 点。 - false：表示不是全天任务。
    └ originorigin任务关联的第三方平台来源信息
      └ platform_i18n_namestring任务来源的名称。 用于在任务中心详情页展示。需要提供一个字典，支持多种语言名称映射。应用在使用不同语言时，导入来源也将展示对应的内容。详细参见：任务字段补充说明
      └ hrefhref任务关联的来源平台详情页链接
        └ urlstring具体链接地址。 URL仅支持解析http、https。详细参见：任务字段补充说明
        └ titlestring链接对应的标题
    └ customstring自定义完成配置。 此字段用于设置完成任务时的页面跳转，或展示提示语。详细参见：任务字段补充说明
    └ sourceint任务创建的来源
可选值有：
- 0: 未知类型 - 1: 来源任务中心创建 - 2: 来源消息转任务 - 3: 来源云文档 - 4: 来源文档单品 - 5: 来源PANO - 6: 来源tenant_access_token创建的任务 - 7: 来源user_access_token创建的任务 - 8: 来源新版云文档
    └ followersfollower\[\]任务的关注者
      └ idstring任务关注人 ID
      └ id_liststring\[\]要删除的关注人ID列表
    └ collaboratorscollaborator\[\]任务的执行者
      └ idstring任务执行者的 ID。 传入的值为 user_id 或 open_id，由user_id_type 决定。user_id和open_id的获取可见文档如何获取不同的用户 ID。
> Info: 已经废弃，为了向前兼容早期只支持单次添加一个人的情况而保留，但不再推荐使用，建议使用id_list字段
      └ id_liststring\[\]执行者的用户ID列表。 传入的值为 user_id 或 open_id，由user_id_type 决定。user_id和open_id的获取可见文档如何获取不同的用户 ID。
    └ collaborator_idsstring\[\]创建任务时添加的执行者用户id列表。 传入的值为 user_id 或 open_id ，由user_id_type 决定。user_id和open_id的获取可见文档：如何获取不同的用户 ID。
    └ follower_idsstring\[\]创建任务时添加的关注者用户id列表。 传入的值为 user_id 或 open_id ，由user_id_type 决定。user_id和open_id的获取可见文档：如何获取不同的用户 ID。
    └ repeat_rulestring重复任务的规则表达式。 语法格式参见RRule语法规范 4.3.10小节
    └ rich_summarystring富文本任务标题。语法格式参见Markdown模块 。创建任务时，任务标题(summary字段)和任务富文本标题(rich_summary字段)不能同时为空，需要至少填充其中一个字段。
    └ rich_descriptionstring富文本任务备注。语法格式参见Markdown模块

响应体示例 ​

json
{
    "code": 0,
    "data": {
        "task": {
            "can_edit": true,
            "complete_time": "0",
            "create_time": "1630304148",
            "creator_id": "ou_05b67908bc5d12a086e909a076f7f1b6",
            "description": "多吃水果，多运动，健康生活，快乐工作。",
            "rich_description": "富文本备注飞书开放平台\n",
            "due": {
                "time": "1623124318",
                "timezone": "Asia/Shanghai"
            },
            "extra": "dGVzdA==",
            "id": "68c9b9ff-d5b5-41bf-b407-6d956f23143f",
            "origin": {
                "href": {
                    "title": "反馈一个问题，需要协助排查",
                    "url": "https://support.feishu.com/internal/foo-bar"
                },
                "platform_i18n_name": "{\"en_us\":\"IT Workspace\",\"zh_cn\":\"IT 工作台\"}"
            },
            "summary": "每天喝八杯水，保持身心愉悦",
            "rich_summary": "富文本标题飞书开放平台\n",
            "custom": "{\"custom_complete\":{\"android\":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}},\"ios\":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}},\"pc\":{\"href\":\"https://www.feishu.cn/\",\"tip\":{\"zh_cn\":\"你好\",\"en_us\":\"hello\"}}}}",
            "update_time": "1630304149",
            "source": 6,
            "collaborators": [
                {
                    "id": "ou_13585843f02bc94923ed17a007cbc9b1"
                },
                {
                    "id": "ou_219a0611de2a639aa939ee97013f37a5"
                }
            ],
            "followers": [
                {
                    "id": "ou_13585843f02bc94923ed17a007cbc9b1"
                },
                {
                    "id": "ou_219a0611de2a639aa939ee97013f37a5"
                }
            ],
            "repeat_rule": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO,TU,WE,TH,FR"
        }
    },
    "msg": "success"
}

错误码 ​

HTTP状态码错误码描述排查建议
4001470400The request failed due to incorrect request parameters.一般可能是请求参数存在问题，导致请求失败，建议根据返回的具体错误进行排查
4011470403The identity token is incorrect. It should be either user_access_token or tenant_access_token.发起请求方的身份token不正确，需要为UserAccessToken或TenantAccessToken其中一种
4001470410Failed to parse rich_summary.富文本标题解析错误，建议检查一下rich_summary是否存在格式错误，语法格式参见Markdown模块
4001470411Failed to parse rich_description.富文本描述解析错误，建议检查一下rich_description是否存在格式错误，语法格式参见Markdown模块
4001470414Invalid timezone.填入的时区信息不合规，建议检查timezone字段是否格式正确，传入值需要符合IANA Time Zone Database标准，规范见Time Zone Database
4001470415Invalid platform_i18n_name.任务导入来源的名称不合规，建议检查platform_i18n_name字段是否格式正确，可能传入了不支持的地区名
4001470416Both summary and rich_summary are empty.标题和富文本标题都没有设置内容，创建任务时要求必须填入其中一个字段
4001470434Invalid repeat rule, please check the format.重复规则无法解析，可能是传入了不正确的格式，请检查是否符合语法规范
4001470435Failed to decode extra by base64.extra字段无法按base64格式解析，请检查传入的内容是否由base64编码后传入
4001470436Failed to parse url of origin, should start with http, https or applink.解析Origin中的URL失败，请检查是否以http、https或applink开头
4001470437Summary or description length exceed limit, the maximum length of summary is 256, the maximum length of description is 65536.任务标题或者描述的文本长度超出限制，标题文本最大长度为256个字符，描述文本最大长度是65536个字符
4001470438Invalid custom, please check the format.Custom字段格式错误，请根据字段说明检查
4001470439Failed to get time by timestamp.无法解析时间戳，请根据字段说明检查时间戳是否符合规范
4291470450There are too many requests currently, please try again later.当前同时发起的请求过多，峰值较高导致了限流，请稍后重新尝试
5001470600Failed to create task.任务创建失败，若重试无法解决，请联系飞书技术人员协助排查
4001470740Text content fails to pass the audit.一般是任务的标题或描述或富文本内容存在非法内容，没有通过安全内容检查

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有