---
url: https://qiwuadmin.com/features/im.md
description: 栖梧的员工即时通讯：私聊、群聊、通讯录、文字、图片、文件、表情、语音消息与前台音视频通话；启用方式、本地缓存、App 原生要求和未完成的真机、分发许可验收。
---

# 员工聊天与通话

员工可以在电脑端和移动 App 里私聊、建群，发送文字、图片、文件、表情和语音消息。前台一对一和最多 8 人的小群音视频通话使用 LiveKit。H5 用于调试和自动化测试；微信小程序没有聊天入口，外部会员、客户也不能加入员工聊天。

::: warning 源码发布与现场可用性
本版提供员工聊天、语音消息和通话的源码及配置说明，不附带已签名的 Android/iOS 安装包，也不预置可用的 LiveKit 服务。

双平台原生插件已有真实 SDK 编译、UTS 链接和模拟器平台测试记录；宿主 App 的签名安装、真实 LiveKit/TURN、Android/iPhone 硬件媒体仍需验收。Android SDK 的一项传递依赖分发许可仍待澄清，不能据此认定最终安装包已经获准分发。具体条件见[App 要求与验收](#app-要求与验收)。
:::

## 启用

1. 更新源码，按[升级模板版本](/guide/upgrade)执行数据库迁移和种子；不要重置已有数据库。
2. 在服务端设置 `APP_IM=true`，重启全部应用实例。默认关闭。
3. 开启[多租户](/features/multi-tenancy)时，确认员工所在租户的套餐包含“聊天”分组。新建该分组时种子会补进已有套餐；管理员后来明确移除后，种子不会自动加回。

员工不需要额外的聊天管理权限。是否能读消息、下载文件或参加通话，由服务端按当前租户、员工身份、会话成员和登录状态核验；超级管理员也不能越过成员边界读取聊天。

电脑端从顶栏的聊天图标进入；App 在“消息”页顶部切换“聊天 / 通知”。关闭开关、套餐不含聊天或当前账号不是员工时隐藏入口。演示模式下聊天只读。

实时通话还需要单独打开 `im.call.enabled`，并配置媒体服务，见[LiveKit 接入](/core/livekit)。**语音消息不需要 LiveKit 服务。**

## 私聊、群聊与消息

* **通讯录**：显示本租户启用的员工和部门，可在本机按姓名、部门搜索，点人直接私聊；不公开手机号、邮箱和用户名。
* **私聊**：同一对员工只有一个会话，不需要好友申请。
* **群聊**：群主、管理员、成员有不同的管理范围；群主可以转让群。新成员看不到加入之前的消息，退出后重新加入也看不到离开期间的内容。
* **消息**：文字、Unicode emoji、图片、文件、24 个内置表情和个人自定义表情。图片先显示缩略图，点开才下载原图。
* **编辑和撤回**：只能编辑自己的文字；自己的消息在规定时间内可以撤回。群主和管理员按群角色规则撤回他人消息。撤回后清除内容及消息附件。
* **已读和未读**：消息显示出来才推进本人的读位置，位置在自己的设备之间同步；不提供逐条已读成员名单。

附件是私有内容，只能经聊天接口按当前成员身份读取。通用文件管理不能绕过这层授权。使用 S3 时，已签发的短时下载地址在有效期内仍可能被持有者使用，退群、撤回无法收回已经下载的副本。

## 本地缓存与待发送消息

电脑端和 H5 使用 IndexedDB，App 使用 SQLite 和本地文件，缓存按服务地址、租户、账号及同步时期隔离。界面优先显示本地会话和消息，再拉取必要的变化；通讯录在本地搜索并通过 ETag 复验。

发送失败可以沿用原消息标识重试；语音文件也随待发送队列持久保存。Web/H5 用 Blob，App 保存到自己的文件目录，成功、过期或主动丢弃时清理。

* 主动退出、被踢、换账号或同步时期变化时清理聊天缓存和附件。
* 会话过期只锁定缓存，同一账号重新登录后可以继续使用；断网和临时服务错误不会清空记录。
* 浏览器只有一个主标签页负责同步和媒体操作。浏览器通话要求 Web Locks，不支持时禁用通话；语音消息不受这一限制。
* 在公用设备上用完请退出登录。本地缓存并不等于加密保险箱。

## 语音消息

点击录音并确认发送，可以取消录制。Web/H5 使用 recorder-core，App 使用系统 RecorderManager；麦克风只在本人主动录音或参加通话时启用。录音和通话互斥占用本端麦克风。

统一上传 WAV：PCM signed 16-bit little-endian、1/2 声道、8000/16000/44100Hz。服务端读取实际文件，核对编码、时长和大小；客户端上报的时长不能覆盖服务端结果。默认最多 60 秒、5 MiB，管理员可以按下面的参数调整。

一次只播放一条。离开会话、锁定、退出、换账号及清库时停止录音和播放；App 中迟到的权限结果不能在页面退出后启动录音。

## 前台音视频通话

在私聊中呼叫对方，或在群聊中选人，含本人最多 8 人。接听前不开麦克风和摄像头；通话中可以静音、启停摄像头、切换前后镜头、选择内置扬声器偏好并挂断。扬声器偏好不保证覆盖有线或蓝牙设备的系统路由。

* 首次接听绑定当前登录会话，其他设备不能接管。
* 同一聊天房间最多一个尚未完成清理的通话；没有覆盖全部设备的员工全局占线约束。
* 群通话中正常离开的非发起者，在通话仍有效且原登录和成员资格有效时可主动重新加入。
* 发起者离开、私聊一方离开、参与者登录结束或资格失效等情况会结束整次通话。
* 接通状态来自媒体 SDK；拿到票据不代表声音和画面已经连通。结束摘要写入聊天，不保存通话录音录像。
* 媒体服务暂时不可达时可能显示“结束中”，后台持续清理，确认完成后才释放房间。不要直接修改数据库把它标为已结束。

**只支持前台通话**：切后台、退出和失去当前页面归属时停止媒体；回到前台不会自动开麦或接听。没有后台来电、锁屏接听、CallKit、离线推送、屏幕共享或录制。

## 管理员参数

在“系统管理 → 参数设置”中修改：

| 参数 | 默认值 | 用途 |
| --- | --- | --- |
| `im.history.retention_days` | `180` | 聊天保留天数；`0` 为永久，只有超级管理员能改 |
| `im.sync.epoch` | 初始随机值 | 恢复备份或重置数据库后换成新值，让客户端重建缓存；不要日常随意修改 |
| `im.group.max_members` | `200` | 群人数上限，含群主 |
| `im.message.edit_minutes` | `5` | 编辑自己的文字的时限 |
| `im.message.recall_minutes` | `2` | 撤回自己的消息的时限 |
| `im.file.max_mb` | `20` | 图片、文件大小上限，同时受存储上限约束 |
| `im.voice.max_seconds` | `60` | 语音时长上限，允许 `1–300` |
| `im.voice.max_mb` | `5` | 语音大小上限，允许 `1–20`，同时受存储上限约束 |
| `im.call.enabled` | `false` | 允许新通话；还须配置 LiveKit，关闭后仍清理已有通话 |

恢复数据库前先备份，并按[源码中的保留与恢复说明](https://github.com/732124645/qiwu-vue-admin/blob/v1.16.0/docs/im.md#保留与恢复)处理同步时期。不要通过 `db:reset` 升级生产库。

## App 要求与验收

* 必须重新编译带 `SQLite`、`Record` 和 `qw-livekit` 的原生整包或自定义基座。旧包只更新 wgt，无法增加这些原生能力。
* 需要自己的 DCloud AppID、包名或 Bundle ID、签名证书，以及手机可访问的 HTTPS API 地址。
* iOS 插件的最低配置为 iOS 15；Android 插件配置最低为 API 21。模拟器工程验证不代表所有低版本、机型和硬件都兼容。
* 原生编译、UTS 链接、模拟器测试、最终宿主签名安装、真实服务和硬件媒体分别验收。现有 HBuilderX/Xcode 组合有已记录的链接适配点，不承诺直接点击 GUI 即可打包安装。
* Android 使用 LiveKit SDK 2.30.0，传递依赖 `android-jain-sip-ri:1.3.0-91` 的版本特定分发授权仍待澄清，见[上游议题](https://github.com/livekit/client-sdk-android/issues/1048)。iOS 和 Android 的上游许可与第三方声明都需要保留并核对最终安装包资源；发布源码不等于已经完成安装包分发许可验收。

部署后用 Android 和 iPhone 核对：录音互播、权限拒绝、扬声器/耳机、镜头切换、系统中断、退出/后台停止，以及 Wi-Fi、蜂窝和禁 UDP 网络下的 TURN。真实服务还要验证房间删除后旧凭据不能重新进入。当前没有这些现场通过记录。

更多开发说明：[移动端开发](/core/mobile) · [LiveKit 部署](/core/livekit) · [原生插件源码与说明](https://github.com/732124645/qiwu-vue-admin/tree/v1.16.0/mobile/src/uni_modules/qw-livekit)。
