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は不要。クエリパラメーターでのトークン指定はサポート終了）
トークンの取得	business.max.ru → Чат-боты → bot → ⋮ → Настройки
レート制限	APIへのリクエストは30件/秒。コールバックへの応答はチャットごとに≤ 2件/秒
メッセージ本文	≤ 4000文字、format：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.modには1.24とありますが、Go ≥ 1.26が必要です）
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）

制約事項 — 違反すると不具合が発生します

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. ミニアプリの認証はサーバー側で行います。 "WebAppData"キーから始まる2段階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
ミニアプリのフロントエンド	references/mini-apps-bridge.md、UI は references/max-ui.md
ミニアプリのバックエンド認証	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
x509 エラーを「修正」するために TLS 検証を無効にする	Russian Trusted Root 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}	更新からチャットを追跡する。1 つのチャットには GET /chats/{chatId} を使う
アップロード先ホストをハードコードする	POST /uploads の url を使う
メッセージ内の Markdown リスト／表	通常の行、見出し、引用を使う
更新ハンドラー内の log.Fatal／未処理エラー	ログに記録して処理を続ける。1 件の不正な更新でボットを停止させない
コールバックのタップを無視する	POST /answers で応答する（チャットあたり ≤ 2 回／秒）

参照先

ファイル	内容
references/sources.md	公式ソース一覧、内容が異なる場合の優先順位、バージョン、最新版の確認方法
references/bot-api.md	エンドポイント、パラメーター、アップロード、制限、エラー、日付付きプラットフォーム変更
references/objects-and-updates.md	メッセージ、添付ファイル、ボタン、Update の種類、Chat、User、コールバック、コメント
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	レート制限、リトライ、チャットの追跡、スケジューリング、分割、冪等性