Appearance
企业微信客户不知道在哪个城市?用 IP 属地给私域客户打城市标签(Node.js 实现)
一个做家装的客户,企业微信里加了 2.3 万个客户,去年想做「同城样板间参观」活动,运营的办法是全员群发。发出去 2.3 万条,点开 700 多条,转化 11 单——算下来一条消息的成本比她投本地信息流还贵。
问题不是文案。她手里有一堆客户,但没有一个字段告诉他「这个人在南京还是合肥」。企微后台有备注、有标签、有来源渠道,唯独没有城市。
这篇讲怎么补上这个字段:在哪采 IP、怎么判城市、怎么打标签、以及哪一步最容易踩坑。
一、先认清一件事:企微接口不给你客户 IP
这是最多人卡住的地方。企微「客户联系」相关接口能拿到的是 external_userid、昵称、备注、添加时间、来源渠道、标签这些,没有 IP 字段。你也不能通过 external_userid 反查任何网络信息。
所以链路必须反过来设计:在你自己能拿到请求的地方采 IP,再把城市带到企微里去。
能采 IP 的触点,按可用性排:
| 触点 | 能不能拿到 IP | 说明 |
|---|---|---|
| 投放落地页 / H5 活动页 | 能 | 最常用,扫码进来就先过你的服务器 |
| 官网、表单、在线客服 | 能 | 和上面一样 |
| 小程序 | 能 | 服务端 wx.request 带上来的请求,拿 X-Forwarded-For |
| 公众号网页授权 | 能 | 授权跳转的中间页在你手上 |
| 直接扫码加好友 | 不能 | 用户在你的页面之外完成,企微只回调事件 |
最后一行是关键。如果你的客户大多是「扫员工活码直接加」,那你根本没见过他的请求,这时候只有两条路:一是把活码换成「落地页 → 领券 → 加好友」的两步流程,二是靠后续的互动(点小程序、进活动页、填地址)慢慢补。别指望一次性把所有人补全,覆盖率能到 60%~70% 就已经很好用了。
二、链路设计:采集、判定、打标分开
真实链路是这样的(代码里为了演示把前两步合并成了一个请求):
客户扫码 → 你的落地页 (/track)
├─ 取真实 IP(可信代理链,从右往左剥)
├─ 查归属地(缓存 + 超时 + 失败降级)
└─ 存一条记录:external_userid / ip / city / 时间 / 来源
↓ 异步
打标签 (/sync)
├─ 确保标签存在(add_corp_tag)
└─ 给客户打标(mark_tag)三个刻意的设计:
**采集和打标分开。**落地页要快,不能因为企微接口慢就把用户卡在那里;打标失败可以重试,落地页卡住就是转化损失。
**标签先建后打。**企微打标签用的是 tag_id,不是标签名。第一次跑要先建标签组,把「城市-杭州」这些建出来,拿到 id 缓存起来,后面直接打。建标签的接口是幂等的(同名不会重复建),但每次都调会白白消耗调用频次。
**城市判不出来就不打标。**境外客户、企业专线出口、IPv6 特殊段,都可能没有城市级数据。这时候宁可不打,也不要打个「城市-未知」进去——半年后你会有一堆脏标签,清理比新建更麻烦。
三、标签体系:省市两级,够用了
我见过有人按区县建标签,跑两个月标签爆了,运营也记不住。建议就两级:
城市-杭州(主用)省-浙江(城市为空但有省时兜底)
再加一个来源维度,方便后面看质量:
城市来源-IP城市来源-自填
**为什么要区分来源。**客户自己在表单里填的城市,永远比 IP 准;IP 只到城市级,而且会被代理、专线、运营商出口带偏。所以正确顺序是:客户自填 > 账号历史地址 > IP。IP 的价值在于「客户什么都没说的时候,给他一个初始值」,以及「客户说的和 IP 差太远时,提醒你复核」。
顺带说个反例:有团队把 IP 城市当成唯一真相,客户明明填了苏州,系统按 IP 判成上海,活动券全发错。这在投诉里是最难解释的一类。
四、Node.js 实现
零依赖,Node 18+ 直接跑(要全局 fetch)。
javascript
// wecom-city-tag.js —— 用 IP 属地给企微客户打城市标签
const http = require('http');
const IP9 = 'https://ip9.com.cn/get';
const CORP_ID = process.env.WECOM_CORP_ID || '';
const SECRET = process.env.WECOM_SECRET || '';
const DRY = !(CORP_ID && SECRET); // 没配凭据就跑干跑模式,只打印标签
const TTL_OK = 6 * 3600 * 1000;
const TTL_FAIL = 60 * 1000;
const cache = new Map(); // ip -> {prov, city, exp}
const inflight = new Map(); // ip -> Promise
async function cityOf(ip) {
const hit = cache.get(ip);
if (hit && hit.exp > Date.now()) return hit;
if (inflight.has(ip)) return inflight.get(ip);
const task = (async () => {
const ac = new AbortController();
const timer = setTimeout(() => ac.abort(), 800);
try {
const resp = await fetch(`${IP9}?ip=${encodeURIComponent(ip)}`, {
signal: ac.signal,
headers: { 'User-Agent': 'wecom-city/1.0' },
});
const body = await resp.json();
const d = body && body.ret === 200 ? body.data || {} : {};
const out = { prov: d.prov || '', city: d.city || '', exp: Date.now() + TTL_OK };
cache.set(ip, out);
return out;
} catch (e) {
// 失败只缓存 1 分钟,别把一次超时钉成 6 小时
const out = { prov: '', city: '', exp: Date.now() + TTL_FAIL };
cache.set(ip, out);
return out;
} finally {
clearTimeout(timer);
inflight.delete(ip);
}
})();
inflight.set(ip, task);
return task;
}
function isPrivate(ip) {
return /^(10\.|192\.168\.|127\.|169\.254\.)/.test(ip)
|| /^172\.(1[6-9]|2\d|3[01])\./.test(ip)
|| /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./.test(ip)
|| ip === '::1' || /^f[cd]/i.test(ip);
}
// 从右往左剥可信代理,返回第一个不可信地址
function realIP(req) {
let remote = (req.socket.remoteAddress || '').replace(/^::ffff:/, '');
if (!isPrivate(remote)) return remote; // 直连不可信,XFF 一律不看
const chain = String(req.headers['x-forwarded-for'] || '').split(',');
for (let i = chain.length - 1; i >= 0; i--) {
const ip = chain[i].trim().replace(/^\[|\]$/g, '');
if (!ip) continue;
if (!isPrivate(ip)) return ip;
}
return remote;
}
// ------- 企微标签 -------
let tokenCache = { token: '', exp: 0 };
const tagIds = new Map(); // 标签名 -> tag_id
async function wecom(path, body) {
const url = `https://qyapi.weixin.qq.com/cgi-bin/${path}`;
const resp = await fetch(url, {
method: body ? 'POST' : 'GET',
headers: { 'Content-Type': 'application/json' },
body: body ? JSON.stringify(body) : undefined,
});
const data = await resp.json();
if (data.errcode !== 0) throw new Error(`${path} errcode=${data.errcode} ${data.errmsg}`);
return data;
}
async function accessToken() {
if (tokenCache.token && tokenCache.exp > Date.now()) return tokenCache.token;
const data = await wecom(
`gettoken?corpid=${encodeURIComponent(CORP_ID)}&corpsecret=${encodeURIComponent(SECRET)}`);
tokenCache = { token: data.access_token, exp: Date.now() + (data.expires_in - 300) * 1000 };
return tokenCache.token;
}
// 一次性把「城市-XX」这组标签建好,再逐个打;标签有总量上限,别按区县铺
async function ensureTags(cities) {
const todo = cities.filter((c) => !tagIds.has(c));
if (!todo.length) return;
if (DRY) {
todo.forEach((c, i) => tagIds.set(c, `dry_${i}`));
return;
}
const token = await accessToken();
const data = await wecom(`externalcontact/add_corp_tag?access_token=${token}`, {
group_name: '客户城市',
tag: todo.map((c) => ({ name: c })),
});
(data.tag_group.tag || []).forEach((t) => tagIds.set(t.name, t.id));
}
async function markCity(token, userid, externalUserid, city) {
if (DRY) return { dry: true, tag: city };
return wecom(`externalcontact/mark_tag?access_token=${token}`, {
userid,
external_userid: externalUserid,
add_tag: [tagIds.get(city)],
});
}
// ------- HTTP -------
const server = http.createServer(async (req, res) => {
const url = new URL(req.url, 'http://x');
res.setHeader('Content-Type', 'application/json; charset=utf-8');
if (url.pathname === '/track') {
const ip = realIP(req);
const info = await cityOf(ip);
const tag = info.city ? `城市-${info.city}` : null;
return res.end(JSON.stringify({
ip, prov: info.prov, city: info.city,
tag, source: info.city ? 'ip' : 'none',
}));
}
if (url.pathname === '/sync') {
// 真实链路:落地页先记下 (external_userid, ip),这里取出来再补打标签
const ip = realIP(req);
const userid = url.searchParams.get('userid') || '';
const extId = url.searchParams.get('external_userid') || '';
const info = await cityOf(ip);
if (!info.city) return res.end(JSON.stringify({ ok: false, why: 'no_city', ip }));
const tag = `城市-${info.city}`;
await ensureTags([tag]);
const out = await markCity(DRY ? '' : await accessToken(), userid, extId, tag);
return res.end(JSON.stringify({ ok: true, ip, city: info.city, tag, out, dry: DRY }));
}
res.end(JSON.stringify({ ok: true }));
});
if (require.main === module) {
server.listen(8091, () => console.log(`listen 8091 dry=${DRY}`));
}
module.exports = { cityOf, realIP, isPrivate, ensureTags, tagIds };接口路径和字段以企微官方文档为准(gettoken、externalcontact/add_corp_tag、externalcontact/mark_tag),不同版本可能有调整,上线前对一遍。
跑起来看看输出:
bash
node wecom-city-tag.js
# listen 8091 dry=true
curl -s -H 'X-Forwarded-For: 223.5.5.5' '127.0.0.1:8091/track'
# {"ip":"223.5.5.5","prov":"浙江","city":"杭州","tag":"城市-杭州","source":"ip"}
curl -s -H 'X-Forwarded-For: 61.139.2.69, 10.8.0.5' '127.0.0.1:8091/track'
# {"ip":"61.139.2.69","prov":"四川","city":"成都","tag":"城市-成都","source":"ip"}
curl -s -H 'X-Forwarded-For: 8.8.8.8' '127.0.0.1:8091/track'
# {"ip":"8.8.8.8","prov":"","city":"","tag":null,"source":"none"}
curl -s -H 'X-Forwarded-For: 36.152.44.95' \
'127.0.0.1:8091/sync?userid=zhangsan&external_userid=wmABC123'
# {"ok":true,"ip":"36.152.44.95","city":"南京","tag":"城市-南京",
# "out":{"dry":true,"tag":"城市-南京"},"dry":true}第三条是重点:境外 IP 返回 city: null,标签不打。这不是 bug,是设计——让不确定的数据留在系统外面,比打进标签里再清理便宜得多。
五、落地时要处理的六件事
**1. 标签有总量上限,别按区县铺。**企微的企业客户标签是有上限的,全国 300 多个地级市 × 各省已经几百个标签,再往下拆到区县就是几千个,运营根本没法用。真想按区县分层,把区县信息存在自己的 CRM 里,标签只留城市。
**2. 打标签要限速。**企微的接口有调用频率限制,群发式的批量打标会被限流。做法是队列 + 分批(每批 50 个,间隔 200ms),失败重试三次后落库等人工。千万别在 for 循环里直接 await 两万次。
**3. external_userid 不是全局唯一的。**同一个客户加了两个不同企业的企微,external_userid 不一样;只有 unionid 能跨主体对齐(需要绑定开放平台)。如果你的客户来自多个企微主体,这一点必须先想清楚,否则标签会打重复。
4. IP 会漂移。同一个客户今天在广州、明天在长沙(出差),标签会被反复改写。建议只打第一次判定的城市,之后的变化记到自己的表里当「活跃城市」,不要每次都覆盖企微标签——标签是给人看的,改来改去运营会迷惑。
**5. 采集 IP 要写进隐私政策。**H5 落地页记录访问 IP,属于收集个人信息,隐私政策里要说明用途(地域化服务)、保存期限。别觉得「IP 不算个人信息」——监管口径里它是。
**6. 别用 IP 覆盖客户自填。**这条前面说过,但它是这类项目最常见的翻车点。实现上就是优先级:自填 > 历史地址 > IP > 不打标。
总结
私域运营真正缺的不是「客户画像」,是几个能直接用来分群的硬字段,城市就是其中最便宜的一个。企微不给 IP,那就自己在落地页上采——把采集、判定、打标拆成三步,异步做,失败不动主流程。
实际效果参考:上面那个家装客户按城市把 2.3 万客户拆成 14 个城市群,同城活动的消息打开率从 3% 涨到 18%,单场样板间活动的到店量翻了三倍。技术上的投入是两天。
查询接口是 GET https://ip9.com.cn/get?ip=<ip>,免费版不注册、支持 IPv4/IPv6,返回 prov、city、country、isp,60 次/分钟的频率限制靠缓存扛(私域场景一个城市的 IP 会反复出现,命中率很高)。要区县粒度(area)或想用 ip_type 把机房、企业出口和家庭宽带分开,那是 VIP 版的能力,细节看 IP9 官网。高并发或者需要多节点容灾时,这套逻辑挪到 Go 或 Java 网关里也一样。