飞书（自建应用）在集成中常见问题解决方法

集简云全渠道连接器，轻松连接飞书（自建应用）与数百款软件系统

通过集简云无代码集成平台，无需开发就可以将飞书（自建应用）无缝集成到各种第三方应用系统，例如：OA办公系统，客户服务系统，MySQL数据库，企业微信，表单系统，CRM等数十款应用系统，以及企业内部系统进行数据同步与功能执行。

查看完整的可用应用列表：https://www.jijyun.cn/apps

一、通讯录动作常见问题

1.通讯录动作出现错误了怎么办？

如果遇到“通讯录动作”出现问题，请点击以下链接，参考【通讯录常见问题】相关文档

【通讯录常见问题】文档：https://open.feishu.cn/document/ugTN1YjL4UTN24CO1UjN/uQzN1YjL0cTN24CN3UjN#e486e304

2.如何高效地使用通讯录接口？

通讯录模块目前包含成员、部门、用户组等几大模块，每个模块都会提供对应的api接口，便于开发者进行智能化的系统对接。开发者对于接口的使用权限主要分为三类：

1）接口的使用权限。定义应用有无权限调用该接口。

2）接口操作的数据权限。定义应用能否对某些数据进行查询或操作。

3）数据字段的权限。由于某些实体（如用户）不同字段的敏感度不同，如用户的手机 ，相对比较敏感，要获取就需要额外的权限。

基于上述三个权限的认知，开发者在进行开发时，可以自行检查，提高开发效率。自行检查确认点为：

1）调用某接口时是否有接口的调用权限，如果没有，接口无法访问；

2）获取或操作某数据时，是否有该数据的通讯录权限，如果没有，会提示无权限；

3）获取某实体的具体字段时是否有该字段的权限，如果没有，可能会获取不到。

3.通讯录权限范围相关问题

1）user_accss_token 与 tenant_access_token 在访问通讯录接口时权限有什么区别？

二者使用获取或操作数据时权限过滤范围不一样。

·tenant_access_token 基于应用的通讯录范围进行权限的过滤，如调用接口获取部门 A 时，会检查部门 A 是否在应用的通讯录权限范围内。其规则配置入口为：Admin管理后台/工作台管理/应用管理。

·user_accss_token 基于用户的可见组织架构范围来做权限过滤，用户可见的组织架构范围为app端上“通讯录”“组织架构”部分可见的架构，其规则配置入口为：登陆Admin管理后台,进入“安全”“用户权限”–“组织架构可见范围”。

2）如何获取企业全部员工信息？

飞书目前没有单独的接口可以获得全部员工信息，如果需要获取，可以按照以下的步骤操作确认：

·确认应用通讯录范围是否为全员，请保证开启为全员。如果不是全员，可能无法获取到全员信息。

·确认通讯录范围为全员后，通过获取部门信息列表接口，设置参数parent_department_id=0，fetch_child=true。获取企业下所有部门ID列表。

·在步骤2获取部门ID列表的基础上，通过获取用户列表等接口搭配使用，来获得全部员工的相关信息。

3）如何获取根部门下的员工通讯录信息？

首先请确保应用的通讯录权限范围设置为“全员”或包含根部门下的所有员工，然后通过获取用户列表接口，设置参数department_id=0，获得根部门下的员工通讯录信息。

4.ID类问题

1）设定好了权限及权限使用的范围，但是仍然获取不到user_id、邮箱、手机 等信息

这里因为user_id、邮箱、手机 等信息比较敏感，需要单独申请相应的权限，无法仅仅通过“获取用户信息权限”这一个权限来获得。详情请参考应用权限文档。

2）同一个用户在多个应用的 open_id 是一样的吗？

不一样。open_id 是用户在应用内唯一标识，因此同一个用户在不同应用中的 open_id 不一致

3）用户在不同企业的 open_id 和 union_id 是不是一样的？

不一样。不同的企业内的用户应算作两个用户，因此进行区分

4）user_id（employee_id） 能不能更新呢？

你可以在创建用户将该用户在企业内部系统已存在的唯一 ID 指定为user_id，若不指定将由系统自动为用户生成一个唯一的随机 ID 作为user_id，已创建用户的 user_id（部分场景也叫 employee_id）不支持更新，因为各应用方都可能用到并保存 user_id, 如果修改 user_id 可能造成应用感知不到，从而造成应用无法使用等问题。

5）user_id 如何获取？

可以通过email或mobile换取，换取方式见接口使用手机 或邮箱获取用户 ID 或者 登录管理后台，点击用户详情，查看获取“用户 ID”。

5.用户/人员相关问题

1）我一不小心误删了部门（或者人员），能不能按照原有的 ID 进行恢复？

目前不能恢复原有的ID。企业的 ID 是唯一的，建议新增一个 ID。

2）我不明白人员的status字段，有详细的注解吗？

可以将该字段对应的数字转化为二进制，对应位数就是对应的值的状态。对照：bit0(最低位): 1冻结，0未冻结；bit1：1离职，0在职；bit2：1未激活，0已激活例：数字“2”转化为二进制就是“010”，意味着“已激活、离职、未冻结”；而数字“0”转化为二进制就是“000”，意味着“已激活、在职、未冻结”。

3）我开发了多个应用，想知道其中某个应用的用户是否也在使用我开发的其他应用。可以通过什么字段来判断？

目前可以使用字段 union_id，一个用户在同一个开发者所属的多个应用中，union_id 唯一

4）搜索用户 接口为什么获取不到返回值？

你可以通过以下方式排查原因：

确认你能在飞书客户端的搜索栏中搜到对应用户，且该用户不是外部用户或离职人员

确认请求参数 page_token 的值是否正确

5）调用手机 或邮箱获取用户 ID/获取用户信息接口时，为什么只能获取自己的，不能获取其他人员的？

请确认相关应用的通讯录权限范围包含包含要获取的用户，而不是只有你自己，如果通讯录范围不包含获取的用户，会返回邮箱或手机 不存在。

6）人员为什么有时候会被拉入其他的部门群？

可以通过如下步骤排查：

确认用户是否有反复修改部门

确认该人员是不是被拉入的部门的负责人

7）系统默认生成的userid，业务方保存userid，删除A员工之后，这个userid会不会被后面新增的员工占用?

系统默认生产成的 userid ，保证了企业内有效（无效表示已离职用户）用户唯一，开发者或管理员对用户进行删除，添加，可能会存在新添加的用户的 userid 和历史上已经删除的用户一样。所以建议增加用户的时候，用具有唯一性标示的id作为 userid ，避免造成困扰（注：部门的自定义ID同理）。

6.用户接口相关问题

1） 创建用户接口 或者 获取单个用户信息 接口请求或应答的结构体内的自定义字段应该如何理解？

用户的 custom_attrs 属性是对用户属性的扩展，用于企业根据自身需求灵活扩展用户描述能力，根据取值语法的不同主要分为文本类型、 页类型、枚举类型、图片类型、用户类型。

文本类型：类用户的 name 属性，只有一个 string 类型的 value。值对应 text 字段

页类型: 字段引用链接，可在成员名片页实现点击跳转效果。该类型字段需要有标题文字，值对应 text 字段，需要有跳转的 url ，值对应 url 。由于PC 端的跳转链接可能会和移动端不太一样，所以单独设置了 pc_url 作为跳转的url，如果该值不填，则 PC 端链接使用 url。

枚举类型： 实现字段取值在给定选项中选择，如员工类型，包含正式、外包、顾问。企业成员的员工类型，只能在这些选项中选择，该类型的值对应 option_id ，也就是管理员配置的某个选项 key 。

图片类型 与枚举类型相似，只是选项的数据类型只能是图片，用于在成员名片页展示其对应的图片，该类型的值对应 option_id，可从管理后台查询对应的图片id。

用户类型 该类型主要用于成员名片页展示对另一用户的引用，实现成员名片页之间的跳转，如将“张三”的 HRBP 字段显示“李四”并支持点击跳转至李四的名片页。对应generic_user 下 id 为需要引用的成员 user_id, generic_user 下的 type 目前固定为1,表示用户类型。

特殊说明：请确保你的组织管理员已在 管理后台/组织架构/成员字段管理/自定义字段管理/全局设置 中开启了“允许开放平台 API 调用“，否则该字段不会生效/返回。如果创建或更新需要对用户新加自定义字段的值，请确保自定义字段的 key 已经被企业管理员创建且有效。

2）创建用户接口企业邮箱字段 enterprise_email 该如使用？

创建用户接口中 enterprise_email 字段表示设置用户的企业邮箱，由于企业邮箱的域名需要企业在管理后台申请并开启。如果企业没有开启对应域名的企业邮箱，设置用户的企业邮箱会操作失败，请联系企业的管理员确认企业是否在后台启用了该域名的企业邮箱。

3）如何理解 获取用户列表 接口？

该接口的设计含义是获取某个部门下的直属用户列表，由于数据的获取受到通讯录权限范围的检查，如果请求带上了部门ID（根部门的部门ID为0），首先会检查应用是有该部门ID的通讯录权限，如果有，就会返回该部门下的直属成员信息（如果带上了department_id=0 表示 check 有没有根部门的通讯录权限，有的话，返回根部门下直属成员信息）；如果请求没有带上部门 ID,无法进行 ID 的通讯录权限校验，就会获取到权限范围内的独立成员（当权限范围包含了某成员，但不包含成员所在部门，则该成员视为权限范围内的独立成员）。所以开发者在使用该接口时，应该结合通讯录的权限以及要获取的数据，来决定如何使用，要不要带部门 ID。

7.部门接口相关问题

1）如何获取父部门下所有员工的通讯录信息？

目前不能通过一个接口来获取父部门下所有员工的通讯录信息，需要通过获取部门信息列表接口获取父部门下所有部门的department_id，然后通过获取用户列表接口获取每个部门下员工的通讯录信息。

2）为什么获取获取部门信息接口获取到 department_id 有时候返回的带 od-，有时候不带？

确认请求是否指定了不同的 department_id_type ，若没指定，默认是open_department_id。

3）如何理解获取 获取部门信息列表 接口？

答：接口语义是获取部门下的子部门信息，由于数据的获取受到通讯录权限范围的检查，如果请求带上了父部门 ID（根部门的部门 ID 为0），首先会检查应用是有该部门 ID 的通讯录权限（如果带上了0，会校验是否有全员权限），如果有，就会返回该部门下部门（根据 fetch_child 为 true 或 false 来决定是否递归）信息；如果请求没有带上父部门 ID,无法进行 ID 的通讯录权限校验，就会根据通讯录权限范围返回数据，如果通讯录范围是全员，就会返回单个根部门 ID 0（开发者可以通过根部门 id 继续请求），否则返回通讯录范围的部门信息。所以开发者在使用该接口时，应该结合通讯录的权限以及要获取的数据，来决定如何使用，要不要带父部门 ID。

8.错误排查

1）使用批量获取信息接口的时候，只返回了部分信息，没有返回全部批量信息。但为什么接口仍会提示任务执行成功， msg 也会返回“success”？

批量接口的返回值是指当前批量任务的执行情况，意味是否执行，而非是否执行成功。只要能开始执行都会记为“执行”。详细的执行情况可以参考查询批量任务执行状态文档。

2）40013 param error 有哪些情况？

可以通过如下步骤排查：

检查一下对应员工/部门的状态，有没有离职 /被删除；

参数错误，具体错误原因可参考 message 信息和表下面的补充，如有疑问，请联系管理员；

手机 已存在，检查手机 是否重复；

手机 和邮箱冲突，检查对应的手机 和邮箱有没有分属于两个不同的飞书账 ，如果存在就需要修改其中一个手机 /邮箱，或者注销掉其中一个账 ；

更新时目标部门下是否有同名部门；

不能更新子部门作为父部门；

自定义文本字段超过默认的100长度限制

3）新增用户返回 email and mobile account conflict 的解决方案？

手机 和邮箱分别注册了两个不同的账 后，手机 和邮箱实际上是对应登录凭证不同的两个账 。在新增用户时同时设置了之前的手机 和邮箱，就会将手机 和邮箱同时作为登录凭证关联到一个账 ，但是之前邮箱和手机 分别在飞书注册了是两个不同的凭证，就会 上面的错误。解决方案是新增的时候只设置手机 ，再去更新邮箱，这样邮箱只是作为一个“属性”而不是登录凭证，或者引导用户注销掉其中一个账 。

4）新增用户返回 department id xxxxxxxx is not exist 的原因？

原因一般有如下三个：

写入的 department id 不存在

open_department_id 和 department_id 是两个不同的 id，是否使用了 open_department_id

应用不在该部门的通讯录权限范围内

二、消息类动作常见问题

1.消息类动作出现错误了怎么办？

如果遇到“消息类动作”出现问题，请点击以下链接，参考【消息与群组 常见问题】相关文档

【消息与群组 常见问题】文档：

https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/guide/faq

2.开发前须知

1）我应该如何使用OpenAPI提供的开放能力？

飞书的OpenAPI开放能力基于Restful接口对外提供服务。

为了方便开发者快速使用，我们总结了一篇文档，参见：如何调用服务端API

2）企业自建应用和应用商店应用ISV的区别是什么？

企业自建应用是指在同一个租户内可以使用的应用，通常情况下，飞书开放平台推荐使用企业自建应用来满足所需功能。

应用商店应用和ISV应用是指注册在应用商店中多个租户都可以使用的应用。创建应用商店应用需要单独进行申请，参见：申请成为飞书ISV

在不同的租户中，appID和clientID相同，但是有不同的tenantKey用于获取tenantToken。不同租户中的botID不同，appID 和tenantKey可以确认一个唯一的botID。

关于自建应用和商店应用更加详细的描述可参见： 自建应用与商店应用

3）在将代码上到生产环境之前，我应该如何方便的进行调试？

飞书的OpenAPI开放能力基于Restful接口对外提供服务，为了方便开发者快速体验和测试各类接口，我们提供了Postman的接口模版，在 Postman模版使用说明中描述了如何利用Postman工具来调试飞书的OpenAPI接口。

如果在使用postman进行接口调试后没有问题，就说明调用接口的参数是正确的。

3.ID类问题

1）app_id和app_secret我应该在哪里获取？

打开飞书开放平台主页，点击我的后台-开发者后台，选择自己的机器人应用

在左侧导航栏中点击「凭证与基础信息」，即可以看到

2）我应该如何获取群组ID（chat_id）?

想要获取chat_id，可以通过一些OpenAPI的接口，我们有以下接口能够获取chat_id：

创建群接口

搜索对用户或机器人可见的群列表接口

具体使用场景和步骤可以参照 群ID 说明。

注意：搜索对用户或机器人可见的群列表接口不支持单聊，只支持群聊

4.机器人相关问题

1）为什么我的机器人在飞书中搜不到？

在申请机器人后，需要做以下两步才可以搜到：

开启机器人能力

打开飞书开放平台主页，点击 我的后台-开发者后台，选择自己的机器人应用，在左侧导航栏的应用功能-机器人标签页中，点击启用机器人能力

将应用发布上线，在应用发布上线成功就可以搜到了。

注意：请确认你选择了正确的机器人应用，以及正确的环境（BOE/Online/海外）

2）提示机器人对某个用户不可见（the bot is invisible to the user），应该如何配置可见性？

配置机器人对某个用户的可见性，是在应用后台对应用发布版本时进行配置的。

打开飞书开放平台主页，点击 我的后台-开发者后台，选择自己的机器人应用

在左侧导航栏中，点击版本管理与发布，再点击右上方的创建版本

3）webhook自定义机器人是什么？ 我应该怎么通过webhook机器人发消息？

群内自定义机器人与你开发的机器人应用有所不同：

自定义机器人只能用于在群聊中自动发送通知，不能响应用户@机器人的消息，不能获得任何的用户、租户信息。

自定义机器人可以被添加至外部群使用，机器人应用只能在内部群使用。

具体使用自定义机器人的方法请见自定义机器人指南

我们还提供了一系列机器人相关使用场景的教程，参见消息与群组概述 中的开发教程

4）在开发者后台配置了机器人，但是为什么我的机器人没有出现对话框？

请确认你的应用配置了订阅事件 址，并且订阅了“接收消息”事件，才会出现对话框。

5）怎么实现机器人@人（@所有人、@指定人）？

在机器人发送的普通文本消息（text）、富文本消息（post）、消息卡片（interactive）中，可以使用at标签实现@人效果。

具体请求示意如下：

(1) 在普通文本消息中@人、@所有人:

at标签示意

// at 指定用户<at user_id=”ou_xxx”>Name</at> //取值必须使用ou_xxxxx格式的 open_id 来at指定人// at 所有人<at user_id=”all”>所有人</at>

请求体中的content 示意：

{ “content”: ” {“text””:””<at user_id=\””ou_xxxxxxxx\””>Tom</at> text content””}””}

(2) 在富文本消息中@人、@所有人:

at标签示意

// at 指定用户{ “”tag””: “”at””