---
docStatus: current
---

# 通讯录与联系方式

从成员目录查询可用联系方式，区分个人联系人、渠道实例和群聊通讯录，并交给对应消息能力发送。

“发给某位同事”首先是联系人解析。通讯录负责说明这个人可以通过哪些方式联系，渠道会话负责具体投递位置。

## 查询个人联系方式

1. 使用工作区管理模块的 `listWorkspaceMembers({})` 确定目标成员。
2. 读取 `listContactMethods` 的定义。当前方法接受整数 `userId` 和可选字符串 `medium`。
3. 用目标成员的真实 `userId` 查询；只需要企业微信时，可将 `medium` 设为 `qiwei`。
4. 读取返回的 `medium`、`identityType`、`identityValue`，按其合同解析联系方式。零结果表示没有查到，多个结果需要明确选择。

`medium` 是联系方式分类或该合同返回的通道值，不能直接当作所有渠道方法的 `channel`。
`identityValue` 的含义由 `identityType` 决定，不能无条件当作 `sessionKey`、平台用户 ID 或渠道实例 ID。

## 通知员工

工作区管理模块提供两个入口，内容都采用 [Content Parts](/integration/content-parts/) 非空有序数组：

| 方法                   | 收件人参数                        | 选择规则              |
| -------------------- | ---------------------------- | ----------------- |
| `notifyEmployee`     | `targetUserId`：工作区员工的平台用户 ID | 系统选择一个启用的渠道绑定联系方式 |
| `sendContactMessage` | `id`：联系方式记录 ID               | 仅使用指定的联系方式        |

两个入口都接受必填的 `content`、`category`、`urgency`，以及可选 `eventId`：

```json
{
  "targetUserId": 42,
  "content": [
    { "type": "text", "text": "有一条客户预约需要你处理。" }
  ],
  "category": "workflow.reply",
  "urgency": "high"
}
```

示例用于 `notifyEmployee`，请把 `targetUserId` 换成成员目录返回的真实 ID。使用 `sendContactMessage` 时，
把收件人字段换为目录返回的联系方式 `id`。不要同时指定两者，也不要传入旧 `message` 字段或对象形态的 `content`。

`category` 是非空业务类别；`urgency` 为 `low`、`normal`、`high`、`critical` 之一，两者独立于内容。
每项内容由自己的 `type` 指明 text、image、audio、video 或 file，不需要外层 `msg_type`。
当前类别和紧急程度会传递给渠道适配器，不改变默认选路，也不保证渠道已支持加急提醒。

工作流调用模块时不需要填写 `workspaceId`、`channel` 或 `sessionKey`。模块注入工作区上下文，
由员工联系方式 owner 核对操作者权限和目标成员状态，再通过 Channel Gateway 投递。
直接使用 owner HTTP 接口时仍必须提供工作区上下文：员工可以属于多个工作区，不能只靠用户 ID 推断。

默认通知使用当前工作区用户设置的 `defaultContactMethodId`。未手动设置时，按联系方式记录 ID 从小到大，
选择第一个已启用且绑定渠道会话的联系方式；`priority` 不参与默认通知选择。
用户可在工作区通讯录的本人联系方式中“设为默认”，或“恢复默认”回到自动选择。
手动设置的联系方式停用或失效时明确报错，不改用其他联系方式；删除默认项前须先清除或改选。
没有可用方式、会话无效或发送失败时显式返回结果，不自动换渠道重发。本人可向自己发送；向其他员工发送要求工作区管理权限。

后端设置接口由联系方式 owner 提供，均为 `POST`：

| 路径                                            | 参数                                     | 作用               |
| --------------------------------------------- | -------------------------------------- | ---------------- |
| `/api/workspace-contact-method/default/get`   | `workspaceId`                          | 读取本人默认设置         |
| `/api/workspace-contact-method/default/set`   | `workspaceId`、`defaultContactMethodId` | 指定本人的一个已启用渠道联系方式 |
| `/api/workspace-contact-method/default/clear` | `workspaceId`                          | 清除手动选择，恢复自动选择    |

操作者来自验签登录身份，接口不接受其他用户 ID。响应包含 `workspaceId`、`userId`、可空的
`defaultContactMethodId`；空值代表未手动设置。读取失败不能视为未设置。接口需要对应后端与管理前端
版本完成交付后使用；不能据此推断目标环境已经升级。

响应包含实际 `contactMethodId`、`targetUserId`、`channel`、`sessionKey`、`delivered`、`category` 和 `urgency`。
以 CModel 的 `errorCode` 和回执 `delivered` 判断结果；HTTP 200 或记录了待办不能当作消息已送达。
`eventId` 只用于消息关联，本接口没有通知队列或幂等重试承诺。

企业微信等渠道仍需先建立真实个人会话并绑定员工。新增通讯录条目不会自动创建外部会话。

## 群聊通讯录

群聊是独立联系目标，不能把群内某个成员当作整个群聊的身份。

- `listGroupChatContacts({})` 查询工作区已绑定群聊。
- 有明确目标时，使用返回的 `contactId`；`sendGroupChatMessage` 的对应参数名为 `id`，准确类型以方法定义为准。
- 没有绑定记录时，先在目标渠道查询实际群聊候选，再通过公开绑定流程建立群聊通讯录；不要猜测群 ID。
- 个人通知选择私聊。发送到群聊会让群成员看到内容，应在业务上明确指定。

群聊发送与个人外部会话发送的 `content` 参数不一定采用相同结构，不能复制另一方法的参数形状。

## 生命周期

成员离职、外部账号解绑、机器人停用或群聊绑定变化后，旧联系方式可能不再可用。
业务配置保存稳定引用，发送前让能力所有者核验有效性；不要维护一套永久有效的联系人快照，也不要在发送失败后自动扩大收件范围。