公众号API 插件使用说明

这个插件把微信公众平台的开放接口封装成了 16 个可以调用的工具。装进扣子的智能体或工作流之后,发文、传素材、抓文章、看数据都能用一句话触发,不用自己拼 HTTP 请求,也不用维护 access_token 的过期逻辑。

插件商店入口:公众号API。

怎么读这份说明: 全文按真实操作的顺序走。先看清工具边界,再做完三项前置配置,然后跑通一条发文链路,最后把选题、复盘、排版三条链路接上。只想赶紧跑起来的,直接跳到第二节。

一、插件能干什么

16 个工具按用途分成四组。同一组里通常挑一个用就行,不需要全部添加,工具加得越多,模型在对话里选错的概率越高。

账号与发文(7 个)

  • get_access_token:换接口凭证,有效期 7200 秒
  • add_draft:存单篇图文草稿
  • add_mult_drafts:一次存多组图文草稿
  • get_draft:把草稿拉回来核对
  • publish_article:发布文章,不推送通知
  • sendall:群发文章并推送通知,需账号已实名认证
  • add_newspic_draft:发图片消息草稿

素材上传(3 个)

  • add_material:永久图片素材,占素材库配额,jpg、png、gif,单张 10MB 以内
  • add_media_material:图片、音频、视频永久素材
  • upload_img:小图上传,不占素材库那 10 万张图片配额,1MB 以内

内容采集(3 个)

  • fetch_mp_article_list:拉指定公众号的文章列表
  • get_history_articles:取历史文章记录
  • extract_wx_article:按文章 URL 解析标题、正文、图片链接

排版与数据(3 个)

  • gzh_ztpeset:自动套用公众号版式模板
  • xhs2xls:小红书图文转公众号小绿书
  • fetch_mp_article_read_count:取阅读、点赞、评论、收藏、分享数据

两个容易混的工具先说清楚。 publish_article 是“发布”,文章上线但不给粉丝推送通知,适合先放出去再择机推广;sendall 是“群发”,会推送通知并占用群发次数。想让粉丝收到提醒用后者,不想打扰粉丝用前者。

二、用之前必须做好的三件事

这三件事都在公众号后台完成,和扣子无关。但少做一步,后面所有工具都跑不通,报错还看不出原因。

1. 把插件的出口 IP 加进白名单

进入公众号后台,依次点“设置与开发”“安全中心”“IP 白名单”,把 47.97.38.108、112.124.10.115 加进去。这是插件的固定出口 IP,不加的话任何接口调用都会返回 40164。白名单里只加这一个就够了,不用把扣子的域名或你自己电脑的 IP 加进去。

2. 拿到 appid 和 secret

微信开发者平台 - 扫码登录 - 我的业务 - 公众号/服务号 - 基础信息 - 开发密钥,即可查看 AppID 和 AppSecret 信息。并且可在此启用、重置或者冻结/解冻 AppSecret。secret 只在生成时出现一次,复制完存好。注意重置会让旧 secret 立即失效,线上正在跑的应用会一起报错。

3. 确认账号有对应权限

未认证的订阅号很多接口不开放,素材、群发都会返回 48001。sendall 还要求账号完成实名认证,这一条在工具说明里也写了。拿不准就别先写智能体,先手动调一次,跑通了再接。

三、跑通第一条链路:从封面到群发

这是最高频的场景,五步走完就是一篇完整的图文。顺序别乱,封面要先生成 media_id,草稿才能引用它。

  1. 取凭证。 调 get_access_token,传入 appid 和 secret,拿到 access_token。有效期 7200 秒,别每次调用都重新取,一天有调用次数上限,缓存起来重复用。
  2. 传封面。 调 add_material,图片限 jpg、png、gif,单张 10MB 以内,返回的 media_id 后面要用。只是临时用一下、不想占素材库那 10 万张配额,改用 upload_img,但它限 1MB 以内、只收 jpg 和 png。
  3. 存草稿。 调 add_draft,传标题、作者、摘要、正文、封面 media_id。正文是 HTML 字符串,样式写法要跟公众号后台一致。一次存多组图文改用 add_mult_drafts。
  4. 核对。 调 get_draft 把草稿拉回来,检查正文有没有被截断、封面有没有传对。这一步别省,发布之后再改麻烦得多。
  5. 发布或群发。 调 publish_article 上线,或者调 sendall 推送通知。两个都传 media_id,不是文章 URL。

在智能体里怎么让它按顺序调。 插件本身不会自己排队。在人设与回复逻辑里写清楚:“用户要求发文时,先调 get_access_token,再调 add_material 传封面,然后调 add_draft 存草稿,等我确认后再调 publish_article”。media_id、access_token 这类中间产物,建议放在工作流里用变量串起来,交给模型自己记很容易丢。

四、另外三条常用链路

找选题:拉列表再拆正文

先调 fetch_mp_article_list 拉目标公众号的文章列表,拿到标题和链接;再对感兴趣的几篇调 extract_wx_article,按 URL 取出完整正文和图片链接。两步连起来,同行最近的选题方向、标题结构、段落节奏就都能拿到,不用手工复制粘贴。要更早的历史文章,用 get_history_articles 补齐。

做复盘:按篇取数据

调 fetch_mp_article_read_count,按文章消息 ID 取阅读量、点赞、评论、收藏、分享。周报场景里,可以让智能体把一周的文章逐个拉一遍,再按阅读量排序,输出哪类选题值得加推。数据口径以公众号后台为准,插件只是搬运。

排版与迁移

gzh_ztpeset 是自动排版,传正文后按模板套版式,现有风格包括洞见风黑白深读、十点读书风暖夜电台、有书风纸页书香、听夜风深夜电台等,需要固定视觉调性的号可以直接用。xhs2xls 用来把小红书图文转成公众号小绿书,多平台分发的号省一次手工搬运。

五、报错对照表

微信返回的错误码比报错文字有用,对照下面几行基本能定位。

错误码含义怎么处理
40001access_token 无效或已过期重新调 get_access_token,把 token 缓存起来按 7200 秒复用
40164调用 IP 不在白名单把 47.97.38.108 加进公众号后台的 IP 白名单
48001接口未授权账号类型或认证状态不满足,先在后台确认该接口是否开放
45009调用超过当日限额降低调用频率,token 走缓存,批量任务分批跑
40007media_id 无效素材可能已删除,或用了另一个公众号的 media_id
40005/40006文件类型或大小不符图片收 jpg、png、gif,单张 10MB 以内;upload_img 另外限 1MB

六、边界与注意事项

  • 草稿不等于发布,发布不等于群发。 add_draft、publish_article、sendall 是三个独立动作,只存草稿粉丝是看不到的。
  • 群发有次数限制。 订阅号一般每天 1 次,服务号一般每月 4 次,具体以后台规则为准。所以批量内容优先走 publish_article。
  • 别把 secret 写进提示词。 放在工作流开始节点、变量或环境变量里传,提示词是对外可见的。
  • 素材库有总量和单文件限制。 长期用会堆满,定期清理,临时图走 upload_img。
  • 发布和群发是对外动作。 建议流程停在草稿,人工确认一次再发,尤其是接入智能体自动跑的时候。

三条链路记住就够了:发文走“取凭证—传封面—存草稿—核对—发布”,选题走“拉列表—拆正文”,复盘走“按篇取数据”。其他工具都是这三条的补充。

0
0
0
0
评论
未登录
暂无评论