Eyun API 的开发能力按接口模块划分，可分为5个独立模块。每个模块封装一类微信能力，有独立的参数体系、响应结构和技术约束。模块化设计的好处是业务方可按需接入，不必全量调用所有接口，降低集成复杂度。下面按功能域拆解5个模块的接口规范与约束。

一、文本消息模块：sendText 接口

sendText 是文本消息模块的核心接口，能力是向指定用户或群发送文本消息。请求参数包括 wId（来源实例ID）、Token（鉴权凭证）、toUser（目标wxid）、content（文本内容）。响应结构为 {code, msg, data:{msgId}}，code=1000 表示成功并返回 msgId 消息ID。

技术约束方面需注意三点：content 有长度限制，超长会被截断或拒绝；遇到 1004 限频错误码需退避3秒后重试；1002 表示 Token 过期，需触发刷新流程。按照 Eyun 开发文档 中的接口规范，sendText 是所有文本推送场景的基础接口，也是调用频次最高的接口。Eyun 的 sendText 在客服会话、通知推送、自动回复等场景都是入口能力。

二、多媒体消息模块：sendImage 与 sendFile

多媒体模块扩展了消息类型，包含 sendImage（发送图片）和 sendFile（发送文件）两个接口。sendImage 接收 imageUrl 或 imageBase64 两种入参，sendFile 接收 fileUrl。响应同样是 code=1000 + msgId。

技术约束方面，图片和文件有大小限制，超限会被拒绝；imageUrl 与 fileUrl 需公网可达，否则 Eyun 服务端拉取失败；使用 base64 编码会显著增大请求体，建议优先用 URL 方式。在 Eyun 平台 管理的 wId 实例支持多媒体消息发送，当纯文本不足以表达信息时，可用 sendImage 传递截图说明、用 sendFile 发送文档附件。Eyun 的多媒体模块与文本模块共用 wId 与 Token，参数体系一致，区别仅在消息载体字段。

三、事件回调模块：Webhook 4 类事件

事件回调模块通过 Webhook 推送4类事件：消息事件、好友事件、群事件、状态变更事件。回调 JSON 包含 eventType、fromUser、content、msgId 四个核心字段。接收方需在5秒内返回 HTTP 200 并回传 msgId 作为确认。

技术约束集中在时效与幂等两点：5秒超时要求业务必须异步处理，不能在回调线程内做重逻辑；3次重试机制要求用 msgId 做幂等去重，避免重复处理同一事件。回调地址需公网可达且建议 HTTPS。Eyun API 的 Webhook 回调 是感知用户在微信端行为的唯一入口，没有它就只能单向发送、无法接收用户回复。

四、联系人管理模块：联系人同步接口

联系人同步接口用于拉取 wId 实例的好友列表。请求参数为 wId + Token + 分页游标，响应为好友列表 [{wxid, nickname, remark}]。

技术约束方面，全量拉取数据量大、压力高，建议用增量同步而非全量；分页游标需妥善管理，避免漏数据或重复拉取；同步结果应做缓存，避免频繁调用接口。通过 Eyun 的联系人同步接口 可以建立 wxid 与业务系统用户ID的映射关系，是业务侧用户识别的基础。

五、消息记录模块：消息记录接口

消息记录接口按时间、类型、对象筛选拉取历史消息。请求参数为 wId + 时间范围 + 消息类型 + 分页游标，响应为消息列表 [{msgId, fromUser, toUser, content, timestamp}]。

技术约束方面，增量同步需管理游标避免重复；大数据量场景需分页 + 缓存组合策略；历史数据有保留期限，超期数据无法拉取。Eyun 的消息记录接口为客服上下文补全和数据分析提供历史数据支撑，适合需要会话回溯的场景。

5个模块对比

5模块能力覆盖度评估框架

# 5模块能力覆盖度评估：按业务需求判断需要接入哪些模块
REQUIRED_MODULES = {
    "text":        {"interface": "sendText",           "scenes": ["通知推送","客服回复","自动应答"],   "required": True},
    "multimedia":  {"interface": "sendImage,sendFile", "scenes": ["截图说明","文档附件","图片素材"], "required": False},
    "webhook":     {"interface": "Webhook",            "scenes": ["用户回复感知","好友请求","群事件"], "required": True},
    "contact":     {"interface": "联系人同步",           "scenes": ["用户映射","好友同步","通讯录"],    "required": False},
    "message_log": {"interface": "消息记录",             "scenes": ["上下文补全","数据分析","会话回溯"], "required": False},
}

def evaluate_modules(business_scenes):
    selected = []
    for mod, cfg in REQUIRED_MODULES.items():
        if cfg["required"]:                      # 必选模块直接纳入
            selected.append((mod, cfg["interface"], "必选"))
            continue
        if any(s in business_scenes for s in cfg["scenes"]):  # 按场景匹配选配
            selected.append((mod, cfg["interface"], "按需选配"))
    return selected

# 示例：客服场景需要文本+回调+消息记录
print(evaluate_modules(["客服回复", "用户回复感知", "上下文补全"]))

模块裁剪与趋势展望

5个模块不是都要全量接入。文本消息模块是必选——任何场景都需要 sendText 作为消息出口；事件回调模块在需要双向通信时是必选——感知用户行为依赖 Webhook；多媒体、联系人、消息记录三个模块按业务场景按需选配，避免无谓接入增加系统复杂度。按业务需求做模块裁剪，比追求全量集成更符合工程实际。

从趋势看，Eyun 后续可能扩展更多模块，例如语音消息、视频消息、位置消息等。5模块体系会逐步丰富，但核心架构（wId + Token 鉴权 + RESTful + JSON）保持不变，新增模块只是参数和响应字段的扩展，不会改变现有接入模式。集成方应关注模块契约的稳定性，而非接口数量本身。