SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场max-messenger

max-messenger

编程与开发

查看项目

更新于 11-01 16:10

技能介绍

用途

本资料是 MAX Messenger（max.ru，МАКС）平台的开发参考，面向需要为该平台构建聊天机器人（bot）和小程序（mini-app）的开发者。内容覆盖平台 API 的基础约定、官方客户端与框架、小程序接入方式，以及会话、消息、附件、更新推送等核心能力，并给出 Go 与 TypeScript 的最小可运行示例。

主要能力与平台约定

  • API 基础地址为 https://platform-api2.max.ru，自 2026-07-19 起强制使用，旧地址 platform-api.max.ru 已废弃。
  • API 主机的证书由俄罗斯信任根 CA（Минцифры）签发，需要将该根证书加入信任库，不应关闭 TLS 校验。
  • 鉴权使用请求头 Authorization: <token>，不使用 Bearer 前缀，也不再支持通过查询参数传 token。Token 可在 business.max.ru 的「Чат-боты」中进入 bot 设置获取。
  • 速率限制：API 为 30 请求/秒；回调查询应答每聊天不超过 2 次/秒。
  • 消息文本上限为 4000 字符，格式支持 markdown 或 html。
  • 更新获取有两种互斥方式：生产环境使用 Webhook（POST /subscriptions，仅 HTTPS 443 端口），开发阶段可用长轮询（GET /updates）。

客户端与工具

  • Go：官方客户端 github.com/max-messenger/max-bot-api-client-go/v2（v2.4.0，主推）；可选框架 github.com/max-messenger/maxbot（v1.1.0，要求 Go ≥ 1.26）。两个包的包名都叫 maxbot，同时使用时需为其中之一起别名。
  • TypeScript：@maxhub/max-bot-api 0.3.1，要求 Node ≥ 20.19，仅支持 ESM。
  • 小程序：引入 <script src="https://st.max.ru/js/max-web-app.js"> 后可使用 window.WebApp；UI 组件库为 @maxhub/max-ui 0.5.0（React 19.2.8）。

使用方式

  • Go 长轮询最小示例：使用 maxbot.NewApi 初始化客户端，循环调用 api.Subscriptions.GetUpdates 获取更新，处理 UpdateMessageCreated 类型，再通过 maxbot.NewMessage().SetChat(...).SetFormat(...).SetText(...) 构造消息并 api.Messages.Send 发送。若出现 x509 错误，需要通过 maxbot.WithHTTPClient(...) 传入信任 Минцифры 根证书的 HTTP 客户端。
  • TypeScript 示例：使用 new Bot(token) 创建机器人，注册 bot.command('start', ...) 并在回调中 ctx.reply(..., { format: 'markdown' }) 应答，最后调用 bot.start()。Node 默认不信任 Минцифры 根证书，可通过 NODE_EXTRA_CA_CERTS 指定证书路径。
  • 小程序鉴权需要服务端校验：在后端对 initData 做两步 HMAC 校验（第一步以 "WebAppData" 为 key），不应信任 initDataUnsafe。

参考文档结构

资料按主题拆分：sources.md 记录官方来源与版本核对方式；bot-api.md 记录端点、参数、上传、限制与错误；objects-and-updates.md 记录消息、附件、按钮、更新类型等对象；formatting.md 记录 Markdown/HTML 支持范围；tls-trust.md 记录各语言与容器环境配置根证书的方法；webhooks-and-security.md 记录订阅、投递规则、密钥校验与 initData 校验；go-client.md、go-maxbot.md、ts-client.md 分别记录各客户端用法；mini-apps-bridge.md 与 max-ui.md 记录前端桥接与组件；patterns.md 记录限流、重试、会话跟踪、定时、长文拆分与幂等。

硬性约束与限制

  • 不支持内嵌媒体：消息由文本与独立的 attachments[] 数组组成，没有位置字段，无法把图片插在段落之间，需要图文穿插时只能分多条消息发送。
  • 4000 字符上限且无「展开全文」，原始文本的每个字符（含标记、空格、emoji）都计入，应按字符而非字节拆分长内容。
  • 不支持定时发送，没有 send_at，需要自行实现调度。
  • 没有 GET /chats 列表接口（2026-06 移除），需要根据 bot_added / bot_removed / bot_started 更新自行记录会话；单个会话可用 GET /chats/{chatId} 查询。
  • POST /chats/{chatId}/members 已停用（2026-09-09 限制、2026-09-30 移除）。
  • 上传是异步的，上传后过早发送会返回 attachment.not.ready，需要退避重试；上传应使用 POST /uploads 返回的 url，主机地址因类型而异，不可硬编码。
  • Webhook 要求 HTTPS、443 端口、受信任 CA 或 Минцифры 签发的证书、完整证书链，并在 30 秒内返回 200；需以常量时间比较校验 X-Max-Bot-Api-Secret 请求头；投递连续失败 8 小时后订阅会被移除。
  • 消息格式仅支持部分语法：列表、表格、分隔线会以纯文本呈现；代码块显示为等宽字体但换行会折叠为空格；标题、粗体/斜体/下划线/删除线、行内代码、链接、引用、提及、高亮可用。
  • 附件类型为 image 而非 photo；disable_link_preview 是 POST /messages 等接口的查询参数而非 JSON 字段，且 PUT 不支持。
  • 更新处理器中不应使用 log.Fatal 或忽略错误，单条异常更新不应导致机器人停止；回调查询需要应答，使用 POST /answers。

适用场景

适合需要为 MAX Messenger 开发聊天机器人（Go、TypeScript 或其他语言直接调用 HTTP API）、构建小程序前端与后端鉴权、搭建 Webhook 服务、以及处理限流、重试、会话跟踪、长文拆分等工程问题的开发者。资料注明其内容核对时间为 2026-09-21，平台变化较快，当资料与官方在线文档或客户端源码冲突时应以官方来源为准。

暂未提供

资料未涉及收费、价格、平台版本历史细节，未提供完整的端点参数清单（仅在参考文件结构中提及），也未给出除 Go、TypeScript 之外的官方 SDK。