企业微信 API 接口：外部联系人（客户）详情获取与标签变更

客户运营离不开两件事拿到客户详情做画像给客户打标签做分层。这篇讲清楚外部联系人的详情怎么获取、标签怎么同步。先搞清外部联系人是什么外部联系人是企微里的客户——微信用户加了你的企微好友或者进了你的客户群。他们的标识是externalUserId外部联系人 id和内部成员的uin不同。关键区分uin内部成员员工或外部联系人的统一 idexternalUserId外部联系人的专属 id同一个客户在不同企微账号下externalUserId可能不同获取客户详情拿到externalUserId后调contact/getExternalContactDetailresp requests.post( f{BASE}/wx-api/api/contact/getExternalContactDetail, headersHEADERS, json{ appid: APPID, externalUserId: wm_xxxx, } ).json()返回的 data 里有name客户昵称avatar头像type客户类型1 微信用户2 企微用户gender性别unionid微信开放平台 unionidfollowUser跟进成员列表哪个员工在跟这个客户批量获取客户列表先拉全部外部联系人resp requests.post( f{BASE}/wx-api/api/contact/getExternalContactList, headersHEADERS, json{appid: APPID} ).json()返回externalUserId列表。要详情再批量调getExternalContactDetail或先拉contact/getSyncList筛客户类型。标签体系企微标签分两种企业标签管理员统一创建全企业通用个人标签员工自己给客户打的仅自己可见API 操作的是企业标签。标签通过label模块管理。给客户打标签label/updateLabel是覆盖式更新——传入的标签列表会替换客户现有标签不是追加def set_labels(external_user_id, tag_ids): resp requests.post( f{BASE}/wx-api/api/label/updateLabel, headersHEADERS, json{ appid: APPID, externalUserId: external_user_id, tagIds: tag_ids, # 覆盖式先拉现有再合并 } ).json() return resp[code] 0关键先调getExternalContactDetail拿现有标签合并后再传否则旧标签会被清掉。标签变更怎么同步客户在企微里被打了标签或标签被移除通过 Webhook 回调推送。事件类型是label_changedef handle_label_change(data): external_user_id data[externalUserId] tag_ids data[tagIds] # 变更后的标签列表 # 同步到 CRM crm.update_customer_tags(external_user_id, tag_ids)回调里带的是变更后的完整标签列表直接覆盖本地即可。标签同步到 CRM 的完整流程# 1. 监听标签变更 def on_label_change(data): uid data[externalUserId] tags data[tagIds] # 2. 查本地客户 customer db.get_customer(uid) if not customer: return # 3. 更新 CRM crm.update_tags(customer[crm_id], tags) # 4. 反向同步CRM 改标签 → 写回企微 def sync_crm_to_wecom(crm_customer_id, new_tags): uid db.get_external_user_id(crm_customer_id) # 先拉现有标签合并 current get_current_tags(uid) merged merge_tags(current, new_tags) set_labels(uid, merged)几个注意点点说明externalUserId 是字符串以wm_开头JSON 里传 string标签是覆盖更新必须先拉后写别直接调回调只推变更后的列表不推变更原因需要自己 diff客户和成员别混externalUserId 和 uin 是两套体系小结客户详情和标签是客户运营的基础设施。详情获取注意 externalUserId 的格式标签同步记住覆盖式更新这个坑。接口用的是Eyun 平台的企业微信 API客户和标签走contact和label模块凭证在官网开通实例时拿到。标签同步的核心是先拉后写、变更监听、双向同步。这三条立住客户画像就能实时更新。