之前帮朋友公司做电商微信自动化的时候遇到过一个特别典型的bug。订单通知功能上线后偶尔会出现发送失败的情况但报错信息是资源不存在。我们检查了好几遍wId和wcId都没问题。最后排查了一下午才发现调用getFriendList时分页参数名写错了——文档写的是pageIndex我们传的是page导致每次拉取的都是第一页的重复数据客户信息匹配不上。一个参数名的细节问题浪费了整个团队一下午的时间。从那以后我就意识到微信API的接入流程和架构设计得再完美也无济于事接口本身的参数细节、返回值含义、适用场景才是真正决定系统稳定与否的关键。这篇文章就从接口视角按类别拆解个人微信API的核心接口讲清楚每个接口是做什么的、关键参数有什么、有哪些容易踩的细节最后结合三个真实项目场景看看这些接口是怎么组合起来实际用的。一、核心接口分类详解以 Eyun平台 的接口规范为例个人微信API的核心接口可以分成三大类消息类、账号类、联系人类。下面逐个讲解重点介绍接口细节不泛泛而谈。1. 消息类接口最常用细节也最多 发送类接口发送文本消息POST /sendText参数类型必填说明wIdstring✅实例IDwcIdstring✅接收方ID。好友格式wxid_xxx群格式xxxchatroomcontentstring✅消息内容一般限制在4000字符内atListlist❌群消息时成员列表传wxid所有人传特殊值all⚠️注意事项醒*content不传入空字符串串直接报1001参数错误发送emoji要注意编码Unicode格可正常显示示部分特殊字符如微信表情的特殊编码可能会报错wcId格式一定要区分好友是wxid_开头群是chatroom结尾传错会直接报1004资源不存在错误在发送图片消息POST /sendImage支持以下两种传参方式请任选其一path本地图片的绝对路径url网络图片URL建议用这个分布式部署时本地路径不好管理限制图片大小一般10MB以内超过会被拒绝。 接收类接口Webhook回调这不是主动调用的接口而是你配置一个回调地址平台会把微信侧的消息/事件推送到你的服务器。回调请求体核心字段字段说明msgId消息唯一标识做幂等处理必须用这个fromUser发送者IDtoUser接收者IDmsgType消息类型text/image/file等content消息内容⚠️踩坑提醒回调必须在5秒内返回响应不然平台会认为推送失触发重试机制重试。业务逻辑耗时长的一定要异步处理同一个msgId可能会推送多次网络超时重试机制必须做幂等处理不然用户会收到一堆重复消息2. 账号类接口实例的生命周期管理 登录接口POST /login两种登录方式方式参数适用场景扫码登录只传wId为空首次登录返回二维码URL手机扫码确认⚠️最大的坑在这里实例掉线后重登如果不传原wcId系统会创建一个新实例旧实例不会自动注销。结果就是同一个微信号挂了多个实例三天两头掉线还容易触发风控。我当时就是不知道这个掉线后直接扫码重登没传wcId结果后面客服号频繁掉线客户消息发不出去投诉了好几单。最后翻 Eyun平台文档 才发现都是没传w导致的惹的祸。 状态查询接口POST /checkStatus参数只有一个wId返回实例是否在线code1000在线其他离线️实战技巧别等用户反馈消息发不出去才去查实例状态。建议写个定时任务每10秒轮询一次所有实例离线重新登录动触发重登记得传wcId。##联系人接口系人类接口通讯录数据同步 获取好友列表POST /getFriendList关键参数wId必填pageIndex页码从1开始重点不是从0开始pageSize每页条数一般最大500⚠️踩坑提醒分页参数名是pageIndex别写成page、pageNum之类的传错了接口不会报错但会一直返回第我朋友公司的那个 bug 就是这么来的。是这么来的。好友多的号一次拉不完一定要做分页循环拉取不要假设一次能拉完。一次能拉完。 搜索联系人POST /searchContact参数wId必填keyword搜索关键词支持昵称、备注、手机号实战用途发送消息前可以先调用这个接口校验 wcId 是否有效避免直接发消息返回“资源不存在”却不知道是哪个环节的问题。个环节的问题。二、 知识点总结三类接口核心要点接口类别核心能力必记细节消息类收发消息、事件推送wcId格式区分回调5秒响应content非空账号类登录、重新登录必须传原wcId必须传原wcId每10秒轮询状态联系人类好友、群、搜索分页参数是pageIndex要做循环分页三、应用场景实战接口上面介绍的都是单个接口实际项目中通常需要将多个接口组合起来使用。下面我将通过三个真实的项目场景来具体说明如何组合使用。看具体怎么组合。场景一电商订单通知自动发送需求背景客户在商城下单后系统自动给客户的微信发订单详情通知。公司每天订单量约2000单。接口组合流程下搜索客户wxid 搜客户wxid → 查实例状态 记录消息ID 记录分类处理错误情况→ 分类处理错误关键点发送前先搜联系人避免wxid失效导致发送消息使用异步队列发消息用异步队列不阻塞下单主流程失败时客户已删除好友不重试已删好友不重试、临时错误网络超时指数退避重试3次场景二多客服号统一监控需求背景客服团队有15个微信号需要统掉线自动重新登录态3次重新登录失败才通知管理员失败才通知管理员。接口组合流程定时任务每10秒→ 遍历15个实例 → 逐个调checkS离线则重新登录(传wcId) → 3次失败发短信 3次失败发短信**关键一定要保存每个实例的原wcId否则后续无法重新登录不然后面15个实例不要同时调用应添加1秒间隔避免一次性调用过于集中而触发限流用太集中触发限流3. 重登成功后更新实例映射wId可能变了场景三CRM客户信息每日同步需求背景每天凌晨2点把微信好友的昵称、备注、头像同步到CRM系统供销售跟进。接口组合流程凌晨2点定时启动 → 分页调getFriendList → 每个好友调searchContact拿详情 → 批量更新CRM关键点凌晨执行避开业务高峰期调用频率放避免占用白天的配额别占着白天的配额同步前先拉总数跟CRM不删除后重新插入更新不删库重插四、 代码实现可直接复用代码1场景一 - 订单通知发送错误分类importrequestsimportlogging loggerlogging.getLogger(order-notice)defsend_order_notice(api_key:str,base_url:str,wid:str,customer_phone:str,order_info:dict)-tuple[bool,str]: 发送电商订单通知 流程搜索联系人 → 检查实例 → 发送消息 → 分类处理错误 Args: api_key: 平台API Key base_url: 平台基础URL这里用 https://www.eyunz.com wid: 实例ID customer_phone: 客户手机号 order_info: 订单信息包含order_id和amount Returns: (是否成功, 成功时返回msgId失败时返回错误描述) headers{Authorization:fBearer{api_key},Content-Type:application/json}# 步骤1搜索客户的wxid try:search_resprequests.post(f{base_url}/searchContact,json{wId:wid,keyword:customer_phone},headersheaders,timeout5)search_datasearch_resp.json()exceptrequests.Timeout:returnFalse,搜索联系人超时临时错误可重试ifsearch_data.get(code)!1000ornotsearch_data.get(data):returnFalse,f客户不存在永久错误{search_data}customer_wcidsearch_data[data][0][wxid]logger.info(f找到客户{customer_wcid})# 步骤2检查实例状态 try:status_resprequests.post(f{base_url}/checkStatus,json{wId:wid},headersheaders,timeout5)exceptrequests.Timeout:returnFalse,状态查询超时临时错误可重试ifstatus_resp.json().get(code)!1000:returnFalse,实重新登录线临时错误重登后再发# 步骤3发送订单通知 content(f您好您的订单{order_info[order_id]}已受理。\nf订单金额¥{order_info[amount]:.2f}\nf感谢您的支持如有疑问请回复咨询~)try:send_resprequests.post(f{base_url}/sendText,json{wId:wid,wcId:customer_wcid,content:content},headersheaders,timeout(5,10)# 连接5秒读取10秒)resultsend_resp.json()exceptrequests.Timeout:returnFalse,发送超时临时错误可重试coderesult.get(code)logger.info(f发送结果code{code}, data{result.get(data)})# 步骤4错误分类处理 ifcode1000:returnTrue,result[data][msgId]# 成功返回msgId供追溯elifcodein(1001,1002,1004):returnFalse,f永久错误不重试{result}else:returnFalse,f临时错误可重试{result}# ############### 调用示例 ###############if__name____main__:success,msgsend_order_notice(api_keysk-xxxxxxxxxxxxxxxx,base_urlhttps://www.eyunz.com,wid实例的wId,customer_phone13800138000,order_info{order_id:DD20260810001,amount:299.00})ifsuccess:print(f✅ 发送成功msgId{msg})else:print(f❌ 发送失败{msg})代码2场景二 - Webhook回调幂等处理importredisimportthreadingimportloggingfromtypingimportCallable loggerlogging.getLogger(webhook-handler)classOrderWebhookHandler: 微信消息回调处理器 核心机制幂等处理 异步执行业务逻辑 def__init__(self,redis_url:strredis://localhost:6379):self.redisredis.Redis.from_url(redis_url)defhandle(self,payload:dict,process_callback:Callable): 处理回调必须5秒内返回所以业务逻辑异步执行 Args: payload: 平台推送的回调数据 process_callback: 业务处理函数比如解析消息、调AI回复等 msg_idpayload.get(msgId)ifnotmsg_id:logger.warning(回调缺少msgId跳过)return# 幂等处理同一个msgId只处理一次 # Redis原子操作SETNX24小时过期keyfwechat:msg:processed:{msg_id}ifnotself.redis.set(key,1,nxTrue,ex86400):logger.info(f重复消息已跳过{msg_id})return# 已处理直接返回不做任何操作logger.info(f新消息开始处理{msg_id})# 异步执行业务逻辑 # 生产环境建议用Celery/RQ等专业消息队列# 这里用线程池简化演示def_exec():try:process_callback(payload)logger.info(f消息处理成功{msg_id})exceptExceptionase:# 处理失败时删除幂等标记允许下一次重试self.redis.delete(key)logger.error(f消息处理失败{msg_id}, error:{e},exc_infoTrue)threading.Thread(target_exec,daemonTrue).start()# ############### 使用示例 ###############handlerOrderWebhookHandler()defprocess_customer_reply(payload:dict):你的业务逻辑比如解析客户消息调AI回复通过API发回去from_userpayload[fromUser]msg_typepayload[msgType]contentpayload.get(content,)logger.info(f收到客户消息from{from_user}, type{msg_type}, content{content[:50]})# TODO: 这里写你的业务逻辑# 1. 关键词判断订单/物流/售后等# 2. 调AI生成回复# 3. 调用/sendText发回去pass# 在Flask/FastAPI中接收回调fromflaskimportFlask,request,jsonify appFlask(__name__)app.route(/wechat/webhook,methods[POST])defwebhook():payloadrequest.json handler.handle(payload,process_customer_reply)# 立即返回5秒内必须响应业务逻辑在线程里异步跑returnjsonify({code:0,msg:ok})五、 总结个人微信API的核心接口分三类消息类收发、账号类生命周期、联系人类数据同步。每类接口都有容易忽略的细节分页参数是pageIndex不重新登录必须传原wcId否则会创建新实例d回调必须在5秒内响应且需做幂等处理秒内响wcId格式需区分好友和群d格式要区分好友和群实际应用中接口都是组合着用的订单通知搜索 状态多客服监控状态查询 重新登录状态查询 重登CRM同步分页拉取 详情查询把接口细节吃透再结合场景合理组合才能真正发挥微信自动化的价值。