企业微信 API 实战系列（一）：构建基于“动态行为”的自动化公海流转系统

一、业务场景：私域线索的"僵尸化"危机

在私域运营中，企业最核心的资产是"外部联系人"。然而，大多数团队面临着"线索躺平"的困境：销售 A 加了客户后，由于精力有限或跟进意愿不强，导致客户在 3 天内没有任何互动。在传统的管理模式下，这名客户会被锁死在销售 A 的列表里，直到被客户拉黑。

这种"人力驱动"的模式不仅浪费了昂贵的引流成本，也让潜在的成单机会白白流失。我们需要通过 API 构建一套"系统驱动"的公海流转机制：只要客户在规定时间内未被"激活"，系统自动剥夺归属权，将其流转至公海或分配给高绩效员工。

二、技术方案设计

利用 QiWe API（官网地址），我们构建一个"静默监听器"：

数据采集：通过 v1/contact/list 获取所有员工的客户详情，重点关注 last_msg_time（最后通话时间）。
规则引擎：设定流转阈值（如：72小时未互动）。
自动化执行：调用 v1/staff/transfer 接口，实现无感知的客户迁移。
实时通知：通过消息接口告知新接收销售，并同步 CRM 记录。

三、核心代码实现

以下代码展示了如何使用 Python 构建一个自动化的流转任务脚本。

python 复制代码

import requests
import time
import datetime

# 基础配置信息
API_BASE = "https://api.qiweapi.com/v1"
TOKEN = "YOUR_QUWE_TOKEN"  # 从 https://www.qiweapi.com/ 获取
HEADERS = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}

def auto_recycle_to_public_pool():
    """
    自动回收超时未互动的客户至公海
    """
    # 1. 定义流转规则：3天未互动（秒为单位）
    TIMEOUT_LIMIT = 3 * 24 * 3600 
    CURRENT_TIME = int(time.time())

    # 2. 获取需要审计的员工列表（可从CRM同步或通过API获取）
    # 更多接口详见：https://doc.qiweapi.com/
    staff_response = requests.get(f"{API_BASE}/staff/list", headers=HEADERS)
    staff_list = staff_response.json().get("data", [])

    for staff in staff_list:
        userid = staff['userid']
        
        # 3. 获取该员工下的所有客户及最后互动时间
        customer_res = requests.get(f"{API_BASE}/contact/list?userid={userid}", headers=HEADERS)
        customers = customer_res.json().get("data", [])

        for customer in customers:
            external_userid = customer['external_userid']
            last_interact = customer.get('last_message_time', 0)

            # 4. 判断是否触发回收规则
            if (CURRENT_TIME - last_interact) > TIMEOUT_LIMIT:
                print(f"检测到客户 {external_userid} 超时未互动，执行回收...")
                
                # 5. 执行流转：将客户从当前员工转移至公海账号
                transfer_payload = {
                    "handover_userid": userid,
                    "takeover_userid": "PUBLIC_POOL_ACCOUNT_ID", # 公海接收官ID
                    "external_userid": [external_userid],
                    "transfer_success_msg": "您好，系统已为您重新分配专属顾问，竭诚为您服务。"
                }
                
                res = requests.post(f"{API_BASE}/staff/transfer", json=transfer_payload, headers=HEADERS)
                if res.json().get("code") == 200:
                    log_transfer_event(external_userid, userid, "PUBLIC_POOL")

def log_transfer_event(cust_id, from_user, to_user):
    # 此处可对接内部数据库，记录流转日志
    print(f"时间: {datetime.datetime.now()}, 客户: {cust_id}, 从: {from_user} -> 转移至: {to_user}")

if __name__ == "__main__":
    auto_recycle_to_public_pool()

四、避坑与性能优化

• 频率限制：企业微信对转移接口有频率限制。建议在代码中加入 time.sleep(1)，分批次处理，避免触发 45009 错误。

• Token 缓存：千万不要在循环内获取 Token。务必实现在本地或 Redis 缓存 Access Token，有效期建议设为 2 小时。

• 白名单机制：针对某些"超大客户"或"特殊关系客户"，建议在 QiWe 官网的管理后台通过标签（如"白名单"）予以排除，防止被系统误回收。

五、运营总结：从"资产分配"到"资产盘活"

本篇通过 API 解决了私域中最大的"资源错配"问题。自动公海流转系统的上线，通常能为企业带来：

线索利用率提升 40% 以上：不再有被遗忘的客户。
倒逼销售跟进：系统化的考核让员工意识到线索的稀缺性。
服务标准化：无论客户流转到谁手中，通过 API 自动下发的欢迎语都能确保品牌形象的一致。

下一步行动：您可以访问QiWe 官方文档查看具体的 transfer 字段要求，并在测试环境部署上述脚本。