企业官网建设流程全解析

QiWe开放平台提供了后台直登功能，登录成功后获取相关参数，快速Apifox在线测试，所有登录功能都是基于QiWe平台API自定义开发。

向包含外部客户的群聊推送消息，核心在于平衡“自动化效率”与“用户体验”。在二次开发时，主要有两条技术路径。

一、 路径选择：Webhook 还是 Appchat？

1. 群机器人 (Webhook)：

   • 原理：在群聊中开启机器人，获取一个 Webhook URL。

   • 适用：简单的实时提醒、内部数据同步到外部群。

   • 特点：配置极快，但无法实现复杂的业务交互，且对机器人添加数量有限制。

2. 应用消息 (Appchat 接口)：

   • 原理：通过自建应用调用appchat/send接口。

   • 适用：深度业务集成，如发送订单卡片、服务进度条。

   • 特点：样式丰富，支持点击回调，是做业务闭环的首选。

二、 核心开发流程（以 Appchat 为例）

要成功推送一条消息，需要走通以下三个关键环节：

1. 身份鉴权 (AccessToken)

一切调用的基础是access_token。

• 注意：必须使用具备“客户联系”权限的应用Secret。如果权限不匹配，即使拿到了 Token，调用推送接口时也会报权限错误。

2. 定位群聊 (ChatID)

chatid是群聊的唯一标识符。

• 获取方式：外部群的 ID 通常通过“获取客户群列表”接口拉取，或者在创建群的回调事件中拦截并记录到自己的数据库。

3. 消息投递 (API 调用)

使用POST方式向企业微信接口发送 JSON 数据包。

• 推荐样式：尽量使用textcard（文本卡片）。它比纯文本更整洁，包含标题、描述和点击跳转按钮，非常适合引导用户点击查看详情。

三、 开发者必须留心的“潜规则”

很多开发者在本地测试没问题，一上线就报错，通常是因为忽略了以下几点：

• 频率管控：外部群有严格的防骚扰机制。如果同一个应用在短时间内向大量外部群发消息，或者向同一个群高频发消息，会被接口拦截。建议：在代码中增加消息队列（Queue），进行削峰填谷，平滑推送。

• 敏感词过滤：推送的内容如果包含诱导分享、营销骚扰词汇，可能会导致消息发送成功但用户端不可见，甚至导致应用被封禁。

• IP 白名单：确保你的生产服务器 IP 已经填入了企业微信后台的可信 IP 段，否则接口会直接拒绝连接。

• Token 缓存：不要每次推送都去请求一次 Token，那样会触发频率上限。正确的做法是本地缓存 Token，快过期前 5 分钟刷新一次。

四、 架构设计小建议

在实际项目中，建议将“推送”作为一个独立的服务模块。

• 解耦：业务逻辑（如订单成功）只负责产生消息任务并存入数据库/队列。

• 重试机制：针对网络波动导致的errcode: -1（系统繁忙），推送模块应具备指数退避的重试逻辑。

• 日志溯源：记录每一条msgid和返回的errcode。当客户反馈没收到消息时，这是你唯一排查问题的依据。

总结：外部群推送的核心不在于接口本身，而在于对规则的敬畏和对频率的控制。