b31in/smart-wx-demo

Fork 0

Files

T

b31in 94784ee1ec wip

2026-01-12 18:01:04 +08:00

7.9 KiB

Raw Permalink Blame History

企业微信外部客户引流与识别系统 PRD

需求概述

实现一个基于企业微信的外部客户引流与识别系统，根据用户与企业的关系状态（是否已添加为外部联系人），引导用户进入不同的业务流程。

核心需求点

用户的入口(二维码) 二维码是哪里生成的? 需要带什么参数?
用户扫码后, 判断当前用户是否已添加该企业微信的外部用户
如果是该企业的外部客户, 跳转到该企业的具体应用页面, 如果不是该企业的外部客户则生成添加企业的二维码页面(这里的逻辑该如何处理)

技术方案

1. 二维码生成方案

1.1 使用企业微信「联系我」接口

api doc: 客户联系「联系我」管理

接口地址: POST https://qyapi.weixin.qq.com/cgi-bin/externalcontact/add_contact_way

推荐配置（临时会话模式）:

{
  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 客户状态判断流程

// 用户扫码后的处理流程
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 已添加客户流程

触发条件: 客户已在企业外部联系人列表中
处理动作:
- 直接跳转到企业应用页面
- 传递客户标识和渠道参数
- 可根据客户标签进行个性化页面展示
示例URL: https://app.yourcompany.com/home?external_userid=xxx&source=channel_001

3.2 未添加客户流程

触发条件: 客户不在企业外部联系人列表中
处理动作:
- 生成永久「联系我」二维码（非临时会话）
- 展示引导页面，说明添加后的服务内容
- 记录引流渠道，用于后续数据分析
二维码配置:

{
  type: 1,
  scene: 2,
  user: ["service_staff_id"],
  is_temp: false,              // 永久添加
  state: "permanent_add_xxx",  // 记录来源
  skip_verify: true,
  remark: "官网引流转化"
}

4. 接口调用流程

4.1 初始化阶段

调用 add_contact_way 接口生成引流二维码
保存返回的 config_id 和 qr_code URL
将二维码部署到各引流渠道

4.2 用户扫码阶段

用户扫码后，企业微信推送事件到回调URL
回调事件包含 external_userid 和 state 参数
后端接收事件，调用 get_external_contact 获取客户详情
根据客户状态执行分流逻辑

4.3 事件回调处理

回调事件类型:

change_external_contact: 外部联系人变更事件
add_external_contact: 添加外部联系人事件
del_external_contact: 删除外部联系人事件

关键参数:

UserID: 接待人员的企业微信ID
ExternalUserID: 外部联系人ID
State: 二维码中的state参数

7.9 KiB Raw Permalink Blame History Unescape Escape