Appearance
钉钉自建应用插件
当您需要使用钉钉自建应用插件时，可以参考以下文档进行配置和使用。
1. 插件介绍
1.1 功能介绍
通过此接口，您可以向指定的成员或部门发送文本消息、Markdown格式信息、
文本卡片等多种类型的消息。
1.2 效果展示
注意：此部分展示了消息通知接口消息卡片类型使用后的效果。
其它类型的效果将在后面展示。
2. 使用前配置
2.1 为您的钉钉账号获取开发者权限
- 使用管理员账号登录钉钉管理后台。
- 选择
安全与权限-权限管理-子管理员-添加子管理员,为您的账号配置相应的权限。
提示
温馨提示：详细流程可以查看钉钉开发者文档。
2.2 使用您的账号创建一个自建应用
- 登录钉钉开放后台。
- 点击应用开发并创建一个新应用。
2.3 为自建应用添加应用能力和申请通讯录权限
- 进入自建应用详情。
- 点击
添加应用能力,添加网页应用。
- 点击
网页应用,设置首页地址为会众云平台实际访问地址。
- 点击
权限管理,设置可以查看的员工范围,分别搜索通讯录部门成员读权限和通讯录个人信息读权限和通讯录部门信息读权限并申请权限。
2.4 使自建应用上线
- 在
版本管理与发布中发布一个新版本。
2.5 在平台中新增自建应用记录
- 获取自建应用的基础信息。
- 回到平台，选择 自建应用信息表单。
- 点击右上方的 “+记录” 按钮，填写相关信息后(不用填写accessToken)点击 “提交”。
- 选择刚刚新增的自建应用信息,点击 “手动刷新token” 按钮。
注意
温馨提示：所有自建应用的token每隔一小时会自动刷新,如果没有刷新可以手动刷新或检查一下自建应用的基础信息是否正确。
3. 通讯录相关接口使用说明
3.1 获取指定应用的所有部门信息接口
获取指定应用权限范围里所有的部门信息。
接口调用效果如下:
参数说明
接口调用时，需要传入以下 参数：
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| AppID | 文本 | ✔️ | 应用唯一标识（UnifiedAppId）,可用于获取应用的基本信息、配置信息、数据等。 |
使用示例
- 选择 “自建应用信息”。
- 点击 “获取并更新应用所有部门” 按钮。
- 选择 “部门信息” ,查看更新的部门信息。
注意
说明：只能获取该自建应用能获取到的部门信息。(跟应用所设定的权限有关,具体设置在本文2.3的第4步有讲)
注意
温馨提示：部门信息有视图可以显示上下级关系。 
3.2 获取指定应用的所有员工信息接口
获取指定应用权限范围里所有的员工信息。
接口调用效果如下:
参数说明
接口调用时，需要传入以下 参数：
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| AppID | 文本 | ✔️ | 应用唯一标识（UnifiedAppId）,可用于获取应用的基本信息、配置信息、数据等。 |
使用示例
- 选择 自建应用信息。
- 点击 “获取并更新应用所有员工” 按钮。
- 选择 员工信息 ,查看更新的员工信息。
注意
说明：只能获取该自建应用能获取到的员工信息。(跟应用所设定的权限有关,具体设置在本文2.3的第4步有讲)
注意
温馨提示：返回的数据可能会存在相同的员工信息,只是员工所在的部门不同。
4. 消息通知相关接口使用说明
消息通知接口是以某个应用的名义推送到员工的工作通知消息，例如生日祝福、入职提醒等。具体消息类型和样例在后面介绍。
4.1 推送文本消息接口
将文本类型的数据推送到员工的工作通知消息。
接口调用效果如下:
参数说明
接口调用时，需要传入以下 参数：
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| 通知内容(文本类型) | 文本 | ✔️ | 消息内容，最长不超过2048个字节。 |
| 通知成员列表 | 子表 | 接收者的userid列表，最大用户列表长度100。 | |
| 通知部门列表 | 子表 | 接收者的部门id列表，最大列表长度20。 | |
| 是否发送给企业全部用户 | 是否 | ✔️ | 是否发送给企业全部用户。 |
| AppID | 文本 | 应用唯一标识（UnifiedAppId）,不选默认自建应用表单第一个应用。 |
提示
说明：当是否发送给企业全部用户设置为否时必须指定userid_list或dept_id_list其中一个参数的值。
使用示例
- 选择名为 “推送文本消息” 功能表单
- 点击右上方的 “+记录” 按钮
- 按照
引导填写相关数据，点击 “提交” 按钮。 - 选择刚刚新增的记录,点击 “推送文本信息” 按钮。
提示
温馨提醒：通知内容，建议500字符以内。
4.2 推送markdown消息接口
将markdown类型的数据推送到员工的工作通知消息。
接口调用效果如下:
参数说明
接口调用时，需要传入以下 参数：
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| 通知内容(markdown文本) | 文本 | ✔️ | markdown格式的消息，最大不超过5000字符。 |
| 通知成员列表 | 子表 | 接收者的userid列表，最大用户列表长度100。 | |
| 通知部门列表 | 子表 | 接收者的部门id列表，最大列表长度20。 | |
| 是否发送给企业全部用户 | 是否 | ✔️ | 是否发送给企业全部用户。 |
| 标题 | 文本 | ✔️ | 首屏会话透出的展示内容。 |
| AppID | 文本 | 应用唯一标识（UnifiedAppId）,不选默认自建应用表单第一个应用。 |
提示
说明：当是否发送给企业全部用户设置为否时必须指定userid_list或dept_id_list其中一个参数的值。
使用示例
- 选择名为 “推送markdown消息” 功能表单
- 点击右上方的 “+记录” 按钮
- 按照
引导填写相关数据，点击 “提交” 按钮。 - 选择刚刚新增的记录,点击 “推送markdown信息” 按钮。
提示
温馨提醒：markdown语法在引导中有简单介绍
4.3 推送消息卡片接口(单个选项)
将消息卡片类型的数据推送到员工的工作通知消息。
接口调用效果如下:
参数说明
接口调用时，需要传入以下 参数：
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| 通知内容(markdown文本) | 文本 | ✔️ | markdown格式的消息，最大不超过5000字符。 |
| 通知成员列表 | 子表 | 接收者的userid列表，最大用户列表长度100。 | |
| 通知部门列表 | 子表 | 接收者的部门id列表，最大列表长度20。 | |
| 是否发送给企业全部用户 | 是否 | ✔️ | 是否发送给企业全部用户。 |
| 标题 | 文本 | ✔️ | 首屏会话透出的展示内容。 |
| 跳转关键字 | 文本 | ✔️ | 跳转选项的标题。必须与跳转地址同时设置，最长20个字符。 |
| 跳转地址 | 文本 | ✔️ | 消息点击链接地址,最长500个字符。 |
| AppID | 文本 | 应用唯一标识（UnifiedAppId）,不选默认自建应用表单第一个应用。 |
提示
说明：当是否发送给企业全部用户设置为否时必须指定userid_list或dept_id_list其中一个参数的值。
使用示例
- 选择名为 “推送消息卡片消息” 功能表单
- 点击右上方的 “+记录” 按钮
- 按照
引导填写相关数据(选择不开启多跳转选项)，点击 “提交” 按钮。 - 选择刚刚新增的记录,点击 “推送消息卡片” 按钮。
提示
温馨提醒：markdown语法在引导中有简单介绍
4.4 推送消息卡片接口(多个选项)
将消息卡片类型的数据推送到员工的工作通知消息。
接口调用效果如下:
参数说明
接口调用时，需要传入以下 参数：
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| 通知内容(markdown文本) | 文本 | ✔️ | markdown格式的消息，最大不超过5000字符。 |
| 通知成员列表 | 子表 | 接收者的userid列表，最大用户列表长度100。 | |
| 通知部门列表 | 子表 | 接收者的部门id列表，最大列表长度20。 | |
| 是否发送给企业全部用户 | 是否 | ✔️ | 是否发送给企业全部用户。 |
| 标题 | 文本 | ✔️ | 首屏会话透出的展示内容。 |
| 选项排列方式 | 单选 | ✔️ | 跳转选项的标题。必须与跳转地址同时设置，最长20个字符。 |
| 跳转列表 | 子表 | ✔️ | 跳转选项的列表,里面有跳转关键字和跳转地址两个字段。 |
| AppID | 文本 | 应用唯一标识（UnifiedAppId）,不选默认自建应用表单第一个应用。 |
提示
说明：当是否发送给企业全部用户设置为否时必须指定userid_list或dept_id_list其中一个参数的值。
使用示例
- 选择名为 “推送消息卡片消息” 功能表单
- 点击右上方的 “+记录” 按钮
- 按照
引导填写相关数据(选择开启多跳转选项)，点击 “提交” 按钮。 - 选择刚刚新增的记录,点击 “推送消息卡片” 按钮。
提示
温馨提醒：markdown语法在引导中有简单介绍
5. 常见问题
Q1: 如何检查接口是否成功调用？
- 答：您可以在工作流中查看调用业务流程的日志，看HTTP请求的状态。