微信修改好友备注接口

前言

在企业私域运营和客户关系管理场景中，给好友打备注是日常高频动作。人工逐一修改不仅效率低下，一旦客户数量超过数百人，备注的规范化更是几乎无法靠手动维护。通过微信修改好友备注接口，可以让系统在客户进线、标签变更、阶段转化等节点自动写入规范备注，大幅提升私域管理效率。本文将从原理到实战，完整讲解如何调用该接口，并给出可直接参考的代码示例。

微信好友备注的业务价值与常见痛点

备注看起来是个小功能，但在实际私域运营中扮演着关键角色。

为什么备注很重要？

识别客户身份：微信昵称用户可以随意修改，昵称本身毫无业务语义；备注才是运营侧对客户的「官方命名」，直接影响后续跟进的准确性。
数据标准化：大型团队往往有统一的备注规范，例如「渠道\_城市\_姓名\_意向等级」，手动维护几乎必然出错。
触发下游流程：部分 SCRM 系统会根据备注关键词触发自动化任务，备注不准确会导致流程断链。

常见痛点：

新员工接手老客资时，数百条备注需要按规范批量重写；
CRM 系统更新客户状态后，微信备注无法联动；
多账号协作场景下，不同设备的备注维护容易出现覆盖冲突。

这些痛点都指向同一个需求：需要一套稳定可编程的微信好友备注接口，能够被业务系统调用，而不是依赖人工操作微信客户端。

接口能力原理：iPad 协议层的备注写入

微信官方对外开放的能力仅限于微信公众号生态，个人微信账号的好友备注没有任何官方 API。市面上能够实现这一功能的方案，几乎全部基于微信 iPad 协议——通过逆向分析微信 iPad 客户端与服务器之间的通信协议，在服务端模拟 iPad 客户端的行为，从而实现登录、好友操作、消息收发等功能。

WechatApi 正是基于 iPad 协议构建的个人微信 HTTP API 服务。其核心架构如下：

业务系统 → HTTP POST 请求 → WechatApi 网关
           ↓
      iPad 协议层（设备模拟）
           ↓
      微信服务器（写入备注）

相比 Hook 注入方案，iPad 协议方案无需在 Windows 或 Android 设备上运行微信客户端，稳定性更高，也不受微信桌面端版本更新的影响。每个接入的微信账号对应一个独立的「设备实例」，在 WechatApi 中以 appId 参数标识。

接口调用规范

鉴权与请求头

WechatApi 个人微信 API 采用固定请求头鉴权，所有接口统一使用：

请求头字段	说明
`VideosApi-token`	在控制台 newmanager.wechatapi.net/dashboard/ 获取，每个账号独立
`Content-Type`	固定为 `application/json`

请求方式统一为 HTTP POST，请求体为 JSON 格式。

业务参数说明

修改好友备注接口的核心参数如下：

参数名	类型	必填	说明
`appId`	string	是	设备 ID，登录微信后由平台分配，对应一个微信账号实例
`toWxId`	string	是	目标好友的微信 ID（wxid\_xxxxx 格式）
`remark`	string	是	要写入的备注内容，支持中英文、数字、空格

返回体结构

接口统一返回 JSON，字段含义如下：

字段	类型	说明
`ret`	int	状态码，200 表示成功
`msg`	string	操作描述，成功时为 "ok"，失败时包含原因
`data`	object	业务数据，备注修改成功时通常为空对象

代码示例：Python 调用修改备注接口

以下示例演示如何用 Python requests 库调用备注修改接口。请将 YOUR_TOKEN 和 YOUR_APP_ID 替换为控制台中的真实值。

pythonimport requests
import json

# 接口配置（endpoint 以实际文档为准）
API_BASE = "https://post.wechatapi.net"
ENDPOINT = "/api/contact/remark"

# 请求头：VideosApi-token 鉴权
headers = {
    "VideosApi-token": "YOUR_TOKEN",
    "Content-Type": "application/json"
}

# 请求体
payload = {
    "appId": "YOUR_APP_ID",       # 设备ID，对应一个登录态微信账号
    "toWxId": "wxid_abcdefg123",  # 目标好友的微信ID
    "remark": "渠道A_上海_张三_高意向"  # 按业务规范写入的备注
}

response = requests.post(
    url=f"{API_BASE}{ENDPOINT}",
    headers=headers,
    data=json.dumps(payload),
    timeout=10
)

result = response.json()

if result.get("ret") == 200:
    print(f"备注修改成功：{payload['remark']}")
else:
    print(f"修改失败，原因：{result.get('msg')}")

接口正常响应示例：

json{
  "ret": 200,
  "msg": "ok",
  "data": {}
}

失败响应示例（好友关系不存在或账号登录态失效）：

json{
  "ret": 500,
  "msg": "not friend or session expired",
  "data": {}
}

批量修改备注的实战场景

单条调用足以应对实时触发场景，但更多时候需要批量处理。以下是一个从 CSV 文件批量读取客户信息并写入备注的示例：

pythonimport requests
import json
import csv
import time

API_BASE = "https://post.wechatapi.net"
ENDPOINT = "/api/contact/remark"

HEADERS = {
    "VideosApi-token": "YOUR_TOKEN",
    "Content-Type": "application/json"
}
APP_ID = "YOUR_APP_ID"

def update_remark(wx_id: str, remark: str) -> dict:
    payload = {
        "appId": APP_ID,
        "toWxId": wx_id,
        "remark": remark
    }
    resp = requests.post(
        url=f"{API_BASE}{ENDPOINT}",
        headers=HEADERS,
        data=json.dumps(payload),
        timeout=10
    )
    return resp.json()

# customers.csv 格式：wx_id,channel,city,name,level
with open("customers.csv", "r", encoding="utf-8") as f:
    reader = csv.DictReader(f)
    for row in reader:
        # 按业务规范拼接备注
        remark = f"{row['channel']}_{row['city']}_{row['name']}_{row['level']}"
        result = update_remark(row["wx_id"], remark)
        
        if result.get("ret") == 200:
            print(f"[OK] {row['wx_id']} → {remark}")
        else:
            print(f"[FAIL] {row['wx_id']}：{result.get('msg')}")
        
        # 避免调用过于密集，每次间隔 0.5 秒
        time.sleep(0.5)

这种模式非常适合以下场景：

从 CRM 导出存量客户列表，按统一规范批量刷新备注；
新员工交接时，将前任员工账号下的客户备注批量迁移到新账号；
定期（如每日 0 点）根据数据库中的客户状态变化，自动更新备注。

与 SCRM 和自动化系统集成

微信 SCRM 系统的核心能力之一就是客户数据的实时同步。将修改好友备注接口嵌入 SCRM 流程，可以实现备注与客户标签、阶段、归属人的自动联动。

典型集成模式：

事件驱动触发：CRM 系统在客户阶段变更时发出 Webhook 事件，后端服务接收事件后调用 WechatApi 的备注接口，将新阶段信息写入微信备注。整个过程无需人工干预，备注实时与 CRM 状态保持一致。

定时同步触发：通过定时任务（如每小时），扫描 CRM 中备注字段与微信实际备注不一致的记录，批量调用接口补齐差异。这种方式容错性更好，适合数据量较大的场景。

bash# 用 curl 快速验证接口连通性（适合运维脚本或 Shell 集成）
curl -X POST "https://post.wechatapi.net/api/contact/remark" \
  -H "VideosApi-token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "appId": "YOUR_APP_ID",
    "toWxId": "wxid_abcdefg123",
    "remark": "测试备注-联调"
  }'

通过 curl 快速验证，可以在正式开发前确认账号登录态是否正常、token 是否有效，避免在代码层面排查底层连接问题。

对于需要同时管理多个微信账号的场景（如客服团队每人一个账号），只需在请求体中切换 appId 字段即可，token 和接口地址保持不变，极大简化了多账号管理的复杂度。这也是微信二次开发场景中 WechatApi 的核心优势之一。

注意事项与常见问题

1. 只能修改单向好友还是双向好友的备注？

修改备注不需要对方同意，操作的是本账号对该联系人的本地备注数据。即便对方删除了你，本地仍然可能存有其联系人记录，但此时再发消息会失败，建议在写备注前先验证好友关系。

2. 备注内容有长度限制吗？

微信对备注长度有限制，建议控制在 30 个字符以内，超长备注会被微信服务端截断或拒绝写入。规范化备注格式（如 渠道_城市_姓名_等级）通常能控制在合理范围内。

3. 修改备注是否会触发微信风控？

单账号短时间内大量修改备注（如每分钟超过 30 条）存在触发风控的风险。生产环境建议：

批量操作时每次调用间隔不低于 500ms；
优先采用事件驱动而非全量定时刷新；
避免在凌晨 0-6 点集中执行大批量操作。

4. appId 是什么，如何获取？

appId 是 WechatApi 平台为每个登录微信账号生成的设备标识符，在控制台完成账号扫码登录后可查看。一个 appId 对应一个微信账号的登录实例，多账号场景下需要分别记录各自的 appId。

5. 账号掉线后备注接口会返回什么？

登录态失效时，接口会返回 ret 非 200 的错误，msg 中会有相应提示。业务侧应捕获此类错误并触发重新登录流程或发出告警，避免静默失败导致备注数据长期不同步。

小结

微信好友备注接口是私域运营自动化的基础能力之一。通过基于 iPad 协议的 WechatApi，开发者可以用标准的 HTTP POST + JSON 方式，配合 VideosApi-token 鉴权和 appId 设备标识，将备注修改操作无缝嵌入 CRM、SCRM 或自动化运营系统中。无论是单条实时触发还是批量定时同步，接口的调用模式都保持一致，集成成本极低。如需了解更多接口能力，可访问开发文档 post.wechatapi.net 或在控制台注册试用。