max-messenger

MAX Messenger 开发

已根据官方来源于 2026-09-21 验证（参见 references/sources.md）。MAX 变化 很快：如果此处的内容与实时文档或客户端源码冲突，请以来源为准。

快速参考

内容	值
基础 URL	https://platform-api2.max.ru（自 2026-07-19 起为必需；旧版 platform-api.max.ru 已弃用）
TLS	API 主机由 Russian Trusted Root CA (Минцифры) 签名——将其添加到信任存储中，绝不要禁用验证 → references/tls-trust.md
身份验证	请求头 Authorization: <token>（不带 Bearer；不再支持查询参数 token）
获取 token	business.max.ru → Чат-боты → bot → ⋮ → Настройки
速率限制	API 每秒 30 个请求；每个聊天的回调答复 ≤ 2 次/秒
消息文本	≤ 4000 个字符，format：markdown 或 html
更新	生产环境使用 Webhook（POST /subscriptions，仅限 443 端口上的 HTTPS）；开发环境使用长轮询（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，尽管其 go.mod 声明为 1.24）
TypeScript	@maxhub/max-bot-api 0.3.1，Node ≥ 20.19，仅支持 ESM
Mini-apps	<script src="https://st.max.ru/js/max-web-app.js"> → window.WebApp；UI 套件 @maxhub/max-ui 0.5.0（React 19.2.8）

硬性限制——违反这些限制会引入错误

1. 主机 + CA。 调用 platform-api2.max.ru。标准 Docker/CI/Node 镜像不信任其 CA，会报错 x509: certificate signed by unknown authority / unable to get local issuer certificate。修复信任 存储（references/tls-trust.md）；绝不要使用 InsecureSkipVerify、NODE_TLS_REJECT_UNAUTHORIZED=0 或 verify=False。
2. 不支持内嵌媒体。 一条消息由 text 和单独的 attachments[] 数组组成，且没有位置/顺序字段， 因此无法将媒体插入段落之间。如需交错发送文本和图片，请分多条消息发送。
3. 4000 个字符，不支持“阅读全文”。 原始 text 中的每个字符都会计入（包括标记、空格、表情符号）； 按字符数而非字节数计算。较长内容请拆分成多条消息（references/patterns.md）。
4. 不支持定时发送。 没有 send_at。请自行运行调度器。
5. 不支持 GET /chats（已于 2026-06 移除）。 请自行根据 bot_added / bot_removed / bot_started 更新记录聊天。单个聊天：GET /chats/{chatId}。
6. POST /chats/{chatId}/members 已停用（2026-09-09 起受限，2026-09-30 起移除）。不要基于此接口构建功能。
7. 上传是异步的。 上传后若发送过早，会返回 attachment.not.ready——请采用退避策略重试。 上传到 POST /uploads 返回的 url；不同类型对应的主机各不相同，绝不要对其进行硬编码。
8. Webhook 规则。 必须使用 HTTPS、443 端口，以及受信任 CA 或 Минцифры 颁发的证书（自签名证书和纯 HTTP 自 2026-05-25 起会被拒绝），并提供完整证书链，在 30 秒内回复 200。使用常量时间比较验证 X-Max-Bot-Api-Secret。交付失败 8 小时后，订阅会被删除。
9. 格式子集。 列表、表格和水平分隔线不受支持——它们会显示为纯文本。代码块会以等宽字体显示，但换行会折叠为空格。标题、粗体/斜体/下划线/删除线、行内代码、链接、引用、提及和高亮均可用（references/formatting.md）。
10. Mini-app 身份验证须在服务端进行。 在后端使用从 "WebAppData" 密钥开始的两步 HMAC 验证 initData；绝不要信任 initDataUnsafe。公式及经过测试的 Go/TS 代码： references/webhooks-and-security.md。

选择你的技术栈

你正在构建	阅读
Go 机器人（默认路径）	references/go-client.md → 原始客户端 NewApi、轮询/ webhook、构造器
带路由/中间件的 Go 机器人	references/go-maxbot.md（客户端上的可选层）
TypeScript / Node 机器人	references/ts-client.md
其他语言 / 原始 HTTP	references/bot-api.md + references/objects-and-updates.md
Mini-app 前端	references/mini-apps-bridge.md，UI 参见 references/max-ui.md
Mini-app 后端认证	references/webhooks-and-security.md
Webhook 服务	references/webhooks-and-security.md + references/tls-trust.md
速率限制、重试、聊天跟踪、调度、长文本	references/patterns.md

两个 Go 包都名为 maxbot。始终使用完整路径导入；如果两个都用，请为其中一个设置别名。

最简机器人

Go — 使用官方客户端进行长轮询：

package main

import (
	"context"
	"log"
	"os"
	"os/signal"
	"time"

	maxbot "github.com/max-messenger/max-bot-api-client-go/v2"
	"github.com/max-messenger/max-bot-api-client-go/v2/model"
)

func main() {
	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
	defer stop()

	api, err := maxbot.NewApi(os.Getenv("MAX_BOT_TOKEN"))
	if err != nil {
		log.Fatalf("init: %v", err)
	}

	var marker int64
	for ctx.Err() == nil {
		updates, next, err := api.Subscriptions.GetUpdates(ctx, marker)
		if err != nil {
			log.Printf("get updates: %v", err)
			select { // back off without ignoring shutdown
			case <-ctx.Done():
			case <-time.After(time.Second):
			}
			continue
		}
		marker = next
		for _, u := range updates {
			if u.UpdateType != model.UpdateMessageCreated {
				continue
			}
			msg := maxbot.NewMessage().
				SetChat(u.ChatID).
				SetFormat(model.FormatMarkdown).
				SetText("**Hi!** Docs: [dev.max.ru](https://dev.max.ru/docs-api)")
			if _, err := api.Messages.Send(ctx, msg); err != nil {
				log.Printf("send: %v", err)
			}
		}
	}
}

如果出现 x509 错误，请传入一个信任 Минцифры 根证书的 HTTP 客户端，使用 maxbot.WithHTTPClient(...) — 参见 references/tls-trust.md。

TypeScript：

import { Bot } from '@maxhub/max-bot-api';

const bot = new Bot(process.env.MAX_BOT_TOKEN!);

bot.command('start', (ctx) =>
  ctx.reply('**Hi!** Docs: [dev.max.ru](https://dev.max.ru/docs-api)', { format: 'markdown' }),
);

bot.start();

Node 默认不信任 Минцифры 根证书：运行时设置 NODE_EXTRA_CA_CERTS=/path/russian_trusted_root_ca.pem（详情参见 references/tls-trust.md）。

常见错误

错误做法	正确做法
https://api.max.ru、https://platform-api.max.ru	https://platform-api2.max.ru
禁用 TLS 验证来“修复” x509 错误	信任俄罗斯可信根 CA
POST /webhook	POST /subscriptions
使用请求体的 HMAC 验证 webhook	X-Max-Bot-Api-Secret 请求头等于你的密钥（使用恒定时间比较）
直接以机器人令牌作为密钥计算 initData HMAC	先推导 secret = HMAC_SHA256("WebAppData", token)
type=photo	type=image
JSON 请求体中的 disable_link_preview	它是 POST /messages、POST /messages/{messageId}/comments 和 POST /answers 的查询参数 — PUT 不支持
GET /chats 或 GET /chats/{link}	根据更新跟踪聊天；对单个聊天使用 GET /chats/{chatId}
硬编码上传主机	使用 POST /uploads 返回的 url
消息中使用 Markdown 列表/表格	使用纯文本行、标题、引用
在更新处理程序中使用 log.Fatal / 未处理错误	记录日志并继续；一条异常更新不应导致机器人停止
忽略回调点击	使用 POST /answers 响应（每个聊天 ≤ 2 次/秒）

参考资料

文件	内容
references/sources.md	所有官方来源、来源冲突时的优先级、版本、如何检查最新信息
references/bot-api.md	端点、参数、上传、限制、错误、注明日期的平台变更
references/objects-and-updates.md	消息、附件、按钮、Update 类型、聊天、用户、回调、评论
references/formatting.md	Markdown 和 HTML 子集、提及、不支持的内容
references/tls-trust.md	Go、Node、Docker、curl、Python 的 Минцифры 根 CA；故障排查
references/webhooks-and-security.md	订阅、投递规则、密钥请求头、initData、电话和联系人哈希
references/go-client.md	官方 Go 客户端 v2：API 接口、构造器、轮询、webhook、上传
references/go-maxbot.md	maxbot 框架：处理程序、上下文、中间件；何时使用
references/ts-client.md	@maxhub/max-bot-api：Bot、处理程序、上下文、键盘、会话、webhook
references/mini-apps-bridge.md	window.WebApp API、initData、深度链接、设置
references/max-ui.md	@maxhub/max-ui 组件和设置
references/patterns.md	速率限制、重试、聊天跟踪、调度、拆分、幂等性