业务平台 · 企微通讯录 API

供运营管理后台等业务系统查询企微内部成员与部门组织架构。 数据来自聊天机器人本地通讯录缓存（与 企微后台 · 通讯录 页默认读库一致； 通讯录回调、本页增删改及「从企微刷新」会更新缓存）。 鉴权方式与 用户同步、聊天记录 API 一致， 使用 X-Chatbot-Webhook-Secret 请求头。

部门接口：/api/public/chatbot/contacts/departments

成员接口：/api/public/chatbot/contacts/members

鉴权

请求头	必填	说明
X-Chatbot-Webhook-Secret	是	与聊天机器人「用户同步」配置的 Webhook 密钥一致（环境变量 PLATFORM_SYNC_WEBHOOK_SECRET 或管理页保存的值）

查询部门列表

响应字段

字段	类型	说明
departments	array	部门列表
departments[].id	int	部门 ID
departments[].name	string	部门名称
departments[].parentId	int	父部门 ID
departments[].order	int	排序值
departments[].syncedAt	string | null	本地缓存更新时间（ISO-8601）

响应示例

{
  "departments": [
    {
      "id": 1,
      "name": "百得健康",
      "parentId": 0,
      "order": 0,
      "syncedAt": "2026-06-11T08:30:00+08:00"
    }
  ]
}

请求示例

curl -sS -G 'https://<chatbot-host>/api/public/chatbot/contacts/departments' \
  -H 'X-Chatbot-Webhook-Secret: <your-secret>'

查询成员列表

Query 参数

参数	类型	说明
department_id 可选	integer	按部门 ID 过滤成员；不传则返回缓存中全部未删除成员。

成员字段

字段	类型	说明
members[].userid	string	企微成员 userid
members[].name	string | null	姓名
members[].alias	string | null	别名
members[].mobile	string | null	手机号（取决于应用权限与补全）
members[].email	string | null	邮箱
members[].position	string | null	职务
members[].gender	int | null	性别：0 未定义，1 男，2 女
members[].enable	int | null	启用状态：1 启用，0 禁用
members[].status	int | null	激活状态：1 已激活，2 已禁用，4 未激活，5 退出企业
members[].statusLabel	string | null	状态中文说明
members[].mainDepartment	int | null	主部门 ID
members[].department	array	所属部门 ID 列表
members[].avatar	string | null	头像 URL（企微 CDN；可能为空）
members[].syncedAt	string | null	本地缓存更新时间

请求示例（按部门）

curl -sS -G 'https://<chatbot-host>/api/public/chatbot/contacts/members' \
  -H 'X-Chatbot-Webhook-Secret: <your-secret>' \
  --data-urlencode 'department_id=2'

查询单个成员

响应为单个成员对象，字段同列表项。成员不在本地缓存时返回 404。

成员头像代理

服务端拉取成员头像二进制（需携带相同鉴权头）。浏览器 <img> 无法自定义请求头时， 请由业务平台后端代理该接口，或直接使用成员对象中的 avatar URL。

错误码

HTTP	说明
401	缺少或错误的 X-Chatbot-Webhook-Secret
503	Webhook 未配置
404	成员不在本地缓存，或头像不存在

前置条件

• 聊天机器人已启用企微通道（WECOM_ENABLED=true）
• 已在「用户同步」页配置 Webhook 密钥
• 本地已有通讯录缓存：在 通讯录 页「从企微刷新」或开启通讯录回调后自动同步

内部管理接口（需登录）：/api/wecom/contact-sync/departments、 /api/wecom/contact-sync/members（支持增删改与 source=api 直拉企微）。