跳到主要内容

HAP如何与飞书对接集成

集成说明​

HAP可以在飞书中以自建应用的方式进行集成。集成后，支持直接将飞书侧的组织架构同步到HAP中，以及在飞书客户端直接打开HAP，另外也支持将应用与工作流消息推送到飞书。

集成步骤​

1、进入HAP组织后台​

组织管理员点击系统头像进入组织管理后台，点击第三方平台，选择飞书进入集成页面。

企业微信、钉钉、飞书只能选择一个平台对接，如果已经对接了一个，另外两个就不再显示了。如何关闭对接

2、打开对接信息页面​

在飞书集成页面，点击【如何获取对接信息？】打开对接信息页面，页面不要关闭，此页面有对接时需要的信息，例如Logo、主页地址等信息。

3、登录飞书开放平台，创建应用​

飞书开放平台地址为 (https://open.feishu.cn/app) ，进入开发者后台，然后点击“创建应用”。

注意：飞书和lark是两个相互独立的平台。HAP仅支持和飞书的对接，请确保您登录的应用后台地址是 open.feishu.cn，而open.larksuite.com 是不支持对接的。

4、填写应用基本信息​

其中应用图标从第2步的打开的对接指南页面中下载。

5、进入飞书应用的详情页​

确定创建应用后，会先进入应用列表，然后点击应用名称进入应用详情。

6、在飞书应用中设置主页地址​

地址从第2步的对接指南页中获取

  • 1)添加应用能力，选择"网页应用"

  • 2)在飞书应用中配置“网页”，记得先添加

  • 3)在安全配置中配置URL

7、启用飞书应用的机器人​

启用机器人功能，这样在飞书消息侧就能直接收到HAP内部的流程、应用消息。

8、添加需要的API权限和数据权限​

需要添加11个接口的权限：

  • 获取应用信息
  • 以应用身份读取通讯录
  • 获取部门基础信息
  • 获取部门组织架构信息
  • 获取用户组织架构信息
  • 获取用户邮箱信息
  • 获取用户受雇信息
  • 获取用户 user ID
  • 获取用户手机号
  • 以应用的身份发消息
  • 给多个用户批量发消息

复制上面的接口名称，逐个搜索后并开通权限。如下图：

设置同步的人员和部门

必须选择[与应用的可用范围一致]。

9、创建发布版本和选择可用人员范围​

飞书中的应用每次做了调整，都需要创建一个发布的新版本以及确认可用人员范围。

10、创建发布版本和设定同步人员范围​

1）应用配置完毕后，需要创建发布版本

如果是更新版本时，记得版本号要增大，如1.0.0 改为1.0.1

2) 配置同步人员范围和应用可见人员范围

这里选择的人员和部门，就是在飞书中可见“HAP”应用的人员，也是同步到HAP的人员和部门。

举个例子：您公司使用飞书的是100人，使用HAP的人数是30人，那么这里就选择那30人，通过部门或指定人员来选择控制范围。

对于后续的同步，都是依据此范围。例如选择了销售部，如果飞书中有员工不在销售部了，再一次同步通讯录时，HAP系统会自动将此人办理离职，如果飞书有新的人加入了销售部，再一次同步通讯录时，HAP会自动同步创建此员工的账号或恢复账号。

如果需要配置全体人员，请从部分人员选项下勾选所有人员和部门，不要直接选择‘全体成员’

3)申请发布

每次调整过应用后，都需要创建新的版本，发布并提交给公司的飞书管理员审核。确保版本是已上架才能正常使用调整后的内容。

根据调整的内容不同，有些是自动审核通过，有些则需要管理员手动操作审核。下图是管理员手动审核的地方。

可以请管理员将此应用设置为免审核，这样我们提交发布申请后自动通过审核。

11、完善HAP中和飞书的对接信息​

将App ID和App Secret写入到下面的地方

如何获取App ID和App Secret

12、同步通讯录​

同步后，会将飞书的人员信息新增到更新同步进HAP

同步前必看​

从飞书的通讯录同步到HAP，是依据手机号和邮箱（优先手机号）进行匹配关联的。

将飞书通讯录同步到HAP，是依据手机号和邮箱（优先手机号）进行匹配关联的。如果HAP的组织中有相同手机号的账户，则直接建立和飞书账号的关联，如果没有则自动创建新的HAP账户。 也就是说，能和现有HAP账户关联有两个条件：

  • 两个平台间绑定的手机号相同

  • HAP账号要在组织内

示例： 在飞书中，员工绑定的手机号是199-9999-9999， 在同步到HAP的组织时，这个组织内有个账户也绑定了手机号199-9999-9999， 如果有则直接关联，如果没有，则自动创建一个新的账户并关联。如果HAP系统中现在有个199-9999-9999的账户，但不在您的组织内，依然不会同步并关联的，而是自动创建一个新的HAP账户。

在手机号匹配不上时，会再按邮箱搜索匹配，在点此查看具体的匹配关联流程

在同步前，管理员要做好及明晰以下3点：

  • 1、确定好使用HAP的飞书账号范围， 范围设置参考本文第9步。

  • 2、已经有HAP账号的且加入组织的员工，一定要让员工核对好HAP账户绑定的手机号和飞书的手机号是否一致，如果不一致，请尽快绑定或换绑保持一致，全部确认后再进行同步通讯录的操作。

  • 3、还没有HAP账户的员工，点击同步后，会自动创建一个HAP账户，账户会绑定一个随机生成的邮箱

13、完成集成​

进入飞书工作台，可以直接打开HAP。

  • 飞书PC端

  • 飞书APP

常见问题​

1、请求非法，请联系应用开发者​

这是因为没有找到重定向地址，请参考第6步，在安全设置中配置重定向URL

2、同步通讯录时，提示接口错误。​

这是因为申请的权限接口缺少，请参考第8步，添加需要的权限。

3、提示同步失败​

文档问题反馈

文档中是否有错别字、内容过期、难以理解等问题？ 点此给我们反馈吧