180 lines
7.9 KiB
Markdown
180 lines
7.9 KiB
Markdown
|
||
# 企业微信外部客户引流与识别系统 PRD
|
||
|
||
## 需求概述
|
||
|
||
实现一个基于企业微信的外部客户引流与识别系统，根据用户与企业的关系状态（是否已添加为外部联系人），引导用户进入不同的业务流程。
|
||
|
||
## 核心需求点
|
||
|
||
1. 用户的入口(二维码) 二维码是哪里生成的? 需要带什么参数?
|
||
2. 用户扫码后, 判断当前用户是否已添加该企业微信的外部用户
|
||
3. 如果是该企业的外部客户, 跳转到该企业的具体应用页面, 如果不是该企业的外部客户则生成添加企业的二维码页面(这里的逻辑该如何处理)
|
||
|
||
## 技术方案
|
||
|
||
### 1. 二维码生成方案
|
||
|
||
#### 1.1 使用企业微信「联系我」接口
|
||
|
||
api doc: [客户联系「联系我」管理](https://developer.work.weixin.qq.com/document/path/92228)
|
||
|
||
**接口地址**: `POST https://qyapi.weixin.qq.com/cgi-bin/externalcontact/add_contact_way`
|
||
|
||
**推荐配置**（临时会话模式）:
|
||
```javascript
|
||
{
|
||
type: 1, // 单人联系
|
||
scene: 2, // 通过二维码联系
|
||
user: ["service_staff_id"], // 接待人员UserID
|
||
is_temp: true, // 开启临时会话
|
||
expires_in: 86400, // 二维码有效期（秒）
|
||
chat_expires_in: 86400, // 会话有效期（秒）
|
||
state: "channel_source_001", // 渠道标识参数
|
||
skip_verify: true, // 无需验证直接添加
|
||
conclusions: {
|
||
text: {
|
||
content: "感谢咨询，如需长期服务请添加我们"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
| 参数 | 必须 | 说明 |
|
||
| --------------- | ---- | ------------------------------------------------------------------------------------------------------ |
|
||
| access_token | 是 | 调用接口凭证 |
|
||
| type | 是 | 联系方式类型，1-单人，2-多人 |
|
||
| scene | 是 | 场景，1-在小程序中联系，2-通过二维码联系 |
|
||
| style | 否 | 在小程序中联系时使用的控件样式，详见附表 |
|
||
| remark | 否 | 联系方式的备注信息，用于助记，不超过30个字符 |
|
||
| skip_verify | 否 | 外部客户添加时是否无需验证，默认为true |
|
||
| state | 否 | 企业自定义的state参数，用于区分不同的添加渠道，在调用"获取客户详情"时会返回该参数值，不超过30个字符 |
|
||
| user | 否 | 使用该联系方式的用户userID列表，在type为1时为必填，且只能有一个 |
|
||
| party | 否 | 使用该联系方式的部门id列表，只在type为2时有效 |
|
||
| is_temp | 否 | 是否临时会话模式，true表示使用临时会话模式，默认为false |
|
||
| expires_in | 否 | 临时会话二维码有效期，以秒为单位。该参数仅在is_temp为true时有效，默认7天，最多为14天 |
|
||
| chat_expires_in | 否 | 临时会话有效期，以秒为单位。该参数仅在is_temp为true时有效，默认为添加好友后24小时，最多为14天 |
|
||
| unionid | 否 | 可进行临时会话的客户unionid，该参数仅在is_temp为true时有效，如不指定则不进行限制 |
|
||
| is_exclusive | 否 | 是否开启同一外部企业客户只能添加同一个员工，默认为否，开启后，同一个企业的客户会优先添加到同一个跟进人 |
|
||
| mark_source | 否 | 是否标记客户添加来源为该应用创建的「联系我」，默认为true；仅对「营销获客」应用生效 |
|
||
| conclusions | 否 | 结束语，会话结束时自动发送给客户，可参考"结束语定义"，仅在is_temp为true时有效 |
|
||
|
||
**关键参数说明**:
|
||
- `state`: 自定义状态参数，用于识别不同引流渠道，建议格式：`channel_{渠道ID}_{场景ID}`
|
||
- `is_temp`: 临时会话模式，不占用企业「联系我」配额，适合首次接触
|
||
- `user`: 指定接待人员，可以是固定客服或根据业务规则分配
|
||
|
||
#### 1.2 二维码参数设计
|
||
|
||
**必需参数**:
|
||
- `state`: 渠道标识（如：`channel_website_homepage`）
|
||
- `user`: 接待人员ID（可配置轮询规则）
|
||
|
||
**可选参数**:
|
||
- `expires_in`: 二维码有效期（建议7天内）
|
||
- `chat_expires_in`: 会话有效期（建议24小时）
|
||
- `conclusions`: 会话结束语（引导正式添加）
|
||
|
||
### 2. 客户识别与分流逻辑
|
||
|
||
#### 2.1 客户状态判断流程
|
||
|
||
```javascript
|
||
// 用户扫码后的处理流程
|
||
async function handleCustomerScan(qrCodeState, externalUserId) {
|
||
// Step 1: 解析渠道信息
|
||
const channelInfo = parseChannelState(qrCodeState);
|
||
|
||
// Step 2: 获取客户详情
|
||
const customerDetail = await getExternalContactDetail(externalUserId);
|
||
|
||
// Step 3: 判断客户状态
|
||
if (customerDetail.external_contact) {
|
||
// 已是外部客户 -> 跳转应用
|
||
return {
|
||
action: "redirect_to_app",
|
||
url: `https://your-app.com/dashboard?channel=${channelInfo.source}&user=${externalUserId}`
|
||
};
|
||
} else {
|
||
// 非外部客户 -> 生成添加二维码
|
||
const addContactWay = await generatePermanentContactWay(channelInfo);
|
||
return {
|
||
action: "show_add_qrcode",
|
||
qrCode: addContactWay.qr_code,
|
||
message: "请添加我们以获得完整服务",
|
||
expiresIn: addContactWay.expires_in
|
||
};
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 2.2 相关接口
|
||
|
||
**获取客户详情**:
|
||
- 接口: `POST https://qyapi.weixin.qq.com/cgi-bin/externalcontact/get`
|
||
- 参数: `external_userid`（从扫码回调中获取）
|
||
- 返回: 客户基本信息、添加状态、标签等
|
||
|
||
**批量获取客户详情**:
|
||
- 接口: `POST https://qyapi.weixin.qq.com/cgi-bin/externalcontact/batch/get_by_user`
|
||
- 用于验证客户是否已添加
|
||
|
||
### 3. 分流处理方案
|
||
|
||
#### 3.1 已添加客户流程
|
||
|
||
1. **触发条件**: 客户已在企业外部联系人列表中
|
||
2. **处理动作**:
|
||
- 直接跳转到企业应用页面
|
||
- 传递客户标识和渠道参数
|
||
- 可根据客户标签进行个性化页面展示
|
||
3. **示例URL**: `https://app.yourcompany.com/home?external_userid=xxx&source=channel_001`
|
||
|
||
#### 3.2 未添加客户流程
|
||
|
||
1. **触发条件**: 客户不在企业外部联系人列表中
|
||
2. **处理动作**:
|
||
- 生成永久「联系我」二维码（非临时会话）
|
||
- 展示引导页面，说明添加后的服务内容
|
||
- 记录引流渠道，用于后续数据分析
|
||
3. **二维码配置**:
|
||
```javascript
|
||
{
|
||
type: 1,
|
||
scene: 2,
|
||
user: ["service_staff_id"],
|
||
is_temp: false, // 永久添加
|
||
state: "permanent_add_xxx", // 记录来源
|
||
skip_verify: true,
|
||
remark: "官网引流转化"
|
||
}
|
||
```
|
||
|
||
### 4. 接口调用流程
|
||
|
||
#### 4.1 初始化阶段
|
||
|
||
1. 调用 `add_contact_way` 接口生成引流二维码
|
||
2. 保存返回的 `config_id` 和 `qr_code` URL
|
||
3. 将二维码部署到各引流渠道
|
||
|
||
#### 4.2 用户扫码阶段
|
||
|
||
1. 用户扫码后，企业微信推送事件到回调URL
|
||
2. 回调事件包含 `external_userid` 和 `state` 参数
|
||
3. 后端接收事件，调用 `get_external_contact` 获取客户详情
|
||
4. 根据客户状态执行分流逻辑
|
||
|
||
#### 4.3 事件回调处理
|
||
|
||
**回调事件类型**:
|
||
- `change_external_contact`: 外部联系人变更事件
|
||
- `add_external_contact`: 添加外部联系人事件
|
||
- `del_external_contact`: 删除外部联系人事件
|
||
|
||
**关键参数**:
|
||
- `UserID`: 接待人员的企业微信ID
|
||
- `ExternalUserID`: 外部联系人ID
|
||
- `State`: 二维码中的state参数
|
||
|