带看 TIM 版快速接入指南

本文档说明带看 TIM 版的完整接入流程，包括服务端接口、Web 展示端、微信小程序端和 App 端配置。

目录

• 1. 接入前准备
• 2. 腾讯云配置
• 3. 服务端配置
• 4. Web 展示端配置
• 5. 微信小程序端配置
• 6. App 端对接指南

1. 接入前准备

接入方需先向众趣申请 app_id 和 app_secret，用于：

• 获取开放平台 token
• 配置 H5 展示端项目环境变量

2. 腾讯云配置

对接方申请对接Tim版带看功能时，需要向众趣提供腾讯云SDKAppID和密钥，用于众趣侧请求腾讯云相关服务接口使用。

2.1 注册腾讯云账号

2.1.1 浏览器登录腾讯云官网:https://cloud.tencent.com/

2.1.2 点击注册，并按腾讯云的页面指导进行注册。

2.1.3 注册成功后，进入腾讯云控制台。

2.2 开通TIM服务

2.2.1 搜索即时通讯IM，并跳转到TIM配置页面

2.2.2 创建新应用

2.2.3 开通服务

2.3 开通TRTC服务

注意：开通TRTC服务需要企业认证， 微信小程序使用trtc服务时，需要额外开通基础服务。

2.4 提供您的密钥

回到TIM应用的基本配置页面。 找到【应用管理】选项卡，记录下您的应用对应的SDKAppID字段和【密钥】字段。

将以上两个字段，和对应的环境（测试、生产）发送给众趣技术人员，进行配置后，即可生效。

2.5 充值和套餐购买

详细信息见腾讯云官方说明: https://cloud.tencent.cn/document/product/647/17157

3. 服务端配置

服务端需要提供回调接口和查询接口。所有接口的校验规则请参考 回调接口规则说明。

3.1 接口总览

类型	接口	说明
回调接口	派单回调	用户发起带看会议时，通知客户服务器进行派单
回调接口	用户加入会议回调	用户加入 TIM 群组且会议进行中时触发
回调接口	用户离开会议回调	用户主动离场或 TIM 离线等场景触发
回调接口	带看会议开始回调	同一场会议内未离开人数首次大于 1 时触发
回调接口	带看会议结束回调	会议主动结束、空房收尾或最后一位用户离场时触发
查询接口	获取指定用户信息	查询带看页面展示所需的用户资料

3.2 接入方需提供的回调接口

3.2.1 派单回调

接口说明

1. 此接口由接入方提供。众趣方在用户发起带看会议时，通过开放平台回调此接口，通知客户服务器进行派单操作。
2. 客户接到回调后，可结合自身业务，如经纪人在线状态、接单规则等，自行决定将本次带看推送给哪些经纪人，并通过 IM、推送等方式拨打给指定经纪人。
3. 接口验证规则请参考 回调接口规则说明。

触发时机

业务侧调用众趣 POST .../takelook/tencent/dispatch/ 或 POST .../takelook/tencent/start/，并指明需要派单时，开放平台会异步向客户推送本回调。该回调与单次 HTTP 响应分离。

接口地址

接入方需提供如下格式的接口地址给众趣方：

https://customer.com/test/api/dispatch/?app_id=xxx&app_secret=yyy

请求示例

请求方法：POST

请求头：Content-Type: application/json;charset=utf-8

URL 校验参数：

https://customer_host.com/api/dispatch/?app_id=1345&timestamp=1532059200000&sign=edb7a6c92c4284fb7e825d63e7258b95&callback_id=877602611346546688

请求体：

{
  "packageId": "ID00001",
  "userId": "1448291745301000000",
  "roomId": "10000123",
  "ext": "{\"responseUserId\":\"1448176777690000000\"}"
}

请求参数

参数名	类型	必填	说明
packageId	string	是	数据包 id，即众趣项目 / 房源 id，对应 project_id
userId	string	是	发起带看的用户 ID
roomId	string	是	会议室 ID。众趣自动生成，后续 SDK 接受带看需要使用该房间号
ext	string	否	客户自定义扩展字段，JSON 字符串，业务侧自行反序列化。例如客户在发起带看时指定接收方 userId，可约定 {"responseUserId":"someUserId"}

URL 上的 app_id、timestamp、sign、callback_id 含义见 回调接口规则说明。

返回示例

{
  "code": 1,
  "msg": "success"
}

返回参数

字段名	类型	必填	说明
code	int	是	1 表示接收派单成功，其余值视为失败
msg	string	否	描述信息

接入方也可以使用 Content-Type: text/plain;charset=utf-8 直接返回字符串 success 表示成功，忽略大小写。详见 回调接口规则说明。

备注

• 若客户响应失败，开放平台会按 30s、4m、30m、1h 间隔重试。
• 派单接口应做幂等处理，同一 callback_id 视为同一次回调。

3.2.2 用户加入会议回调

接口说明

1. 此接口由接入方提供，众趣方通过开放平台调用。
2. 当用户成功加入 TIM 群组且会议室内存在进行中的会议时，众趣带看服务通过开放平台向客户推送该用户的加入事件。
3. 接口验证规则请参考 回调接口规则说明。

触发时机

腾讯 TIM 服务端回调通知用户入群成功，且对应会议室内存在「进行中」的会议时，触发本回调。

接口地址

https://customer.com/test/api/user_joined/?app_id=xxx&app_secret=yyy

请求示例

请求方法：POST

请求头：Content-Type: application/json;charset=utf-8

{
  "project_id": "ID00001",
  "roomId": 10000123,
  "meetingId": 20000456,
  "joinTime": "2026-05-12T12:34:56+08:00",
  "user": "1448291745301000000",
  "isFirstOne": true,
  "meetingStatus": 1
}

请求参数

参数名	类型	必填	说明
project_id	string	是	项目 id，房源 id。无项目上下文时可能为空字符串
roomId	int	是	会议室 ID
meetingId	int	是	会议 ID
joinTime	string	是	用户加入时间，ISO8601 格式
user	string	是	加入会议的用户 ID
isFirstOne	bool	是	该用户是否为本场会议的首位加入者
meetingStatus	int	是	会议状态：0 未开始，1 进行中，2 已结束，以众趣枚举为准

URL 上的 app_id、timestamp、sign、callback_id 含义见 回调接口规则说明。

返回示例

{
  "code": 1,
  "msg": "success"
}

备注

• 同一场会议内可能多次触发本回调，每位用户加入各推送一次。
• 同一场会议在「未离开人数首次大于 1」时会额外触发 带看会议开始回调（service_id=106），每场会议仅推送一次。
• 客户侧需对 callback_id 做幂等处理。

3.2.3 用户离开会议回调

接口说明

1. 此接口由接入方提供，众趣方通过开放平台调用。
2. 当业务侧上报用户离开，或检测到用户 TIM 离线等导致离场时，众趣带看服务通过开放平台向客户推送该用户的离开事件。
3. 接口验证规则请参考 回调接口规则说明。

触发时机

• 业务侧调用众趣 POST .../takelook/tencent/user_left/ 主动上报离场。
• 腾讯 TIM 检测到用户掉线、退群等导致系统判定其已离开会议。

接口地址

https://customer.com/test/api/user_left/?app_id=xxx&app_secret=yyy

请求示例

请求方法：POST

请求头：Content-Type: application/json;charset=utf-8

{
  "room_id": 10000123,
  "meeting_id": 20000456,
  "user_id": "1448291745301000000"
}

请求参数

参数名	类型	必填	说明
room_id	int	是	会议室 ID
meeting_id	int	是	会议 ID
user_id	string	是	离开的用户 ID

URL 上的 app_id、timestamp、sign、callback_id 含义见 回调接口规则说明。

返回示例

{
  "code": 1,
  "msg": "success"
}

备注

• 一场会议的最后一位用户离场时，可能紧接着收到 带看会议结束回调（service_id=107），请勿强依赖文档约定以外的回调顺序。
• 客户侧需对 callback_id 做幂等处理。

3.2.4 带看会议开始回调

接口说明

1. 此接口由接入方提供，众趣方通过开放平台调用。
2. 同一场会议内，未离开人数首次大于 1，即发起者之外的首位用户加入时，触发本回调。
3. 每场会议仅触发一次。
4. 接口验证规则请参考 回调接口规则说明。

接口地址

https://customer.com/test/api/meeting_started/?app_id=xxx&app_secret=yyy

请求示例

请求方法：POST

请求头：Content-Type: application/json;charset=utf-8

{
  "project_id": "ID00001",
  "roomId": 10000123,
  "meetingId": 20000456,
  "startTime": "2026-05-12T12:35:10+08:00",
  "users": "1448291745301000000,1448176777690000000"
}

请求参数

参数名	类型	必填	说明
project_id	string	是	项目 id，房源 id。无项目上下文时可能为空字符串
roomId	int	是	会议室 ID
meetingId	int	是	会议 ID
startTime	string	是	会议开始时间，ISO8601 格式
users	string	是	发起者与首位加入者等用户 ID，逗号分隔

URL 上的 app_id、timestamp、sign、callback_id 含义见 回调接口规则说明。

返回示例

{
  "code": 1,
  "msg": "success"
}

备注

• 「会议开始」严格基于「未离开人数首次大于 1」判定，与 用户加入会议回调（service_id=104）独立，但通常先收到 104 再收到 106。
• 客户侧需对 callback_id 做幂等处理。

3.2.5 带看会议结束回调

接口说明

1. 此接口由接入方提供，众趣方通过开放平台调用。
2. 当会议被主动结束、空房收尾，或最后一位用户离场等情况导致会议关闭时，触发本回调。
3. 接口验证规则请参考 回调接口规则说明。

触发时机

• 业务侧调用众趣 POST .../takelook/tencent/meeting_ended/ 主动结束会议。
• 会议室内最后一位有效成员离开导致空房收尾。
• 其他由服务端判定的会议结束场景。

接口地址

https://customer.com/test/api/meeting_ended/?app_id=xxx&app_secret=yyy

请求示例

请求方法：POST

请求头：Content-Type: application/json;charset=utf-8

{
  "room_id": 10000123,
  "meeting_id": 20000456
}

请求参数

参数名	类型	必填	说明
room_id	int	是	会议室 ID
meeting_id	int	是	会议 ID

URL 上的 app_id、timestamp、sign、callback_id 含义见 回调接口规则说明。

返回示例

{
  "code": 1,
  "msg": "success"
}

备注

• 同一场会议可能先收到若干 用户离开回调（service_id=105），再收到本回调。
• 客户侧需对 callback_id 做幂等处理。

3.3 接入方需提供的查询接口

3.3.1 获取指定用户信息

接口说明

1. 此接口由接入方提供，众趣方通过开放平台调用。
2. 当带看业务需要展示指定用户，如带看发起方、经纪人、参与方等的头像、姓名、角色等资料时，通过本接口由客户服务器查询并返回。
3. 接口验证规则请参考 回调接口规则说明。区别于回调接口，此接口使用 request_id 而不是 callback_id，含义一致。

接口地址

接入方需提供如下格式的接口地址给众趣方：

https://customer.com/test/api/user_info/?app_id=xxx&app_secret=yyy

请求示例

请求方法：GET

https://customer_host.com/api/user_info/?user_id=1448291745301000000&app_id=1345&timestamp=1532059200000&sign=edb7a6c92c4284fb7e825d63e7258b95&request_id=877602611346546688

请求参数

参数名	类型	必填	说明
user_id	string	是	客户侧的用户 ID
app_id	string	是	校验用，参考回调接口规则
timestamp	string	是	校验用，参考回调接口规则
sign	string	是	校验用，参考回调接口规则
request_id	string	是	校验用，参考回调接口规则的 callback_id 字段

返回示例

{
  "code": 1,
  "msg": "success",
  "data": {
    "UserId": "1448291745301000000",
    "UserName": "刘宝",
    "Avatar": "https://customer_host.com/avatar/1448291745301000000.png",
    "RoleId": "1",
    "RoleName": "经纪人",
    "PhoneNumber": "18682300000",
    "ElectronicCard": "https://customer_host.com/card/1448291745301000000.html"
  }
}

返回参数

成功时，建议在 data 字段中返回如下信息。具体字段以双方约定为准。

字段名	类型	必填	说明
UserId	string	是	用户 ID，与入参 user_id 对应
UserName	string	是	用户姓名，带看页面展示用
Avatar	string	否	头像 URL
RoleId	string	否	角色 ID
RoleName	string	否	角色名称
PhoneNumber	string	否	联系电话
ElectronicCard	string	否	电子名片地址

备注

• 客户响应需符合 回调接口规则说明 中「回调接口的响应值」约定，code=1 表示成功。

4. Web 展示端配置

4.1 预先完成

1. 联系众趣人员获取web展示端samplecode源代码包
2. 修改 .env 文件中的环境变量，使用从众趣申请的 app_id 和 app_secret

VITE_APP_ZQ_APPID='' # 众趣开放平台 AppId，对应从众趣申请的 app_id
VITE_APP_ZQ_SECRET='' # 众趣开放平台测试公司 secret，对应从众趣申请的 app_secret
VITE_APP_TAKELOOK3_API_BASE_URL='https://opendev.3dnest.cn' # 众趣开放平台测试环境 host，正式地址为 https://open.3dnest.cn

1. 打包项目，并将打包产物部署到您的服务器上，确保可通过公网访问。

注意：打包项目时，请按实际部署情况修改 vite.config.ts 中的 base 参数。sample code 默认使用 ./。

4.2 使用带看功能

带看功能通过 URL query 参数控制，且仅在移动端模式下生效。访问 H5 页面时，携带如下参数即可开启带看功能。

参数名	类型	必填	说明
useVrTakeSee	0 \| 1	是	是否开启带看功能，1 为开启，默认为 0
startTour	0 \| 1	否	是否自动进入带看，无需用户点击带看按钮，默认为 0
userId	string	是	当前用户 ID
callerUserId	string	是	发起者用户 ID。与 userId 相同则为发起者
meetingId	string	否	带看会议 ID。不传则自动创建，一般发起者 URL 不带此参数，接收者 URL 携带
roomId	string	否	TIM 群组 ID。不传则自动创建，一般发起者 URL 不带此参数，接收者 URL 携带
packageId	string	是	房源 ID
pattern	string	否	呼叫模式，callout 表示呼叫模式
imPlatform	string	否	平台类型：web / app / mp，默认 web
noAudioCall	0 \| 1	否	是否禁用语音通话，1 为禁用
isInMPWeb	0 \| 1	否	是否在微信小程序 webview 中运行，小程序访问时使用
takeSeeTestMode	0 \| 1	否	是否启动接收端二维码弹窗，1 为开启。开启后，发起方等待对方进入阶段会弹出二维码，可使用 App 扫码快速进入，无需等待极光通知

发起方示例链接：

https://beyond.3dnest.cn/nest_vr_sample/?m=b5fabc8e_Xmz4_b6f9&useVrTakeSee=1&userId=custom_01&callerUserId=custom_01&imPlatform=app&house_id=1&noAudioCall=1&startTour=0

接收方示例链接：

https://beyond.3dnest.cn/nest_vr_sample/?m=b5fabc8e_Xmz4_b6f9&useVrTakeSee=1&userId=agent_01&callerUserId=custom_01&imPlatform=app&house_id=1&noAudioCall=1&startTour=0&roomId=123&meetingId=123

5. 微信小程序端配置

5.1 添加服务器地址

开发阶段可不配置，不校验合法域名、web-view 等。

登录微信公众平台，进入 开发 > 开发设置 页面，配置以下服务器地址。

request 合法域名

• https://yun.tim.qq.com
• https://opendev.3dnest.cn（众趣测试环境）
• https://opend.3dnest.cn（众趣正式环境）

socket 合法域名

• wss://wss.im.qcloud.com
• wss://wss.tim.qq.com

uploadFile 合法域名

• 如业务或 SDK 涉及文件、图片、音视频上传，请按实际上传服务补充对应的 HTTPS 域名。

业务域名

• 接入方自己部署的展示端项目 HTTPS 域名。

配置完成后，可在微信公众平台的服务器域名页面查看 request、socket、uploadFile 等配置项。

5.2 开放语音权限

<live-player> 和 <live-pusher> 需要先满足开放类目要求，并在小程序后台开通组件权限。推荐添加 工具 > 视频客服 类目。

微信官方对 live-player 组件开放类目的说明中，工具 > 视频客服 可用于一对一视频客服场景：

添加类目

进入 设置 > 基本设置 > 基本信息 > 服务类目，点击 添加服务类目。

在服务类目中选择 工具 > 视频客服 并提交审核。审核通过后，服务类目列表中会展示 工具 > 视频客服 条目。

开通组件权限

需要先通过类目审核，再在小程序管理后台进入 开发与服务 > 开发管理 > 接口设置 > 接口权限，在 其他接口 中自助开通 live-player 和 live-pusher 组件权限。

5.3 微信小程序 Demo 项目

我们提供了微信小程序对接的 Demo 项目，可下载参考：点击下载

注意：请使用微信开发者工具导入 Demo 项目进行编译和运行，详细指南见Demo项目的README.md。

6. App 端对接指南

接入带看 TIM 版功能，需要在您的 App 程序（Android 和 iOS）中接入众趣提供的带看 SDK。对接详情请下载sdk插件, 按照对接指导文档进行对接。

6.1 Android

• 下载 SDK
• SDK 对接指导文档
• 示例 Demo 下载

6.2 iOS

• 下载 SDK
• SDK 对接指导文档
• 示例 Demo