Download the PHP package grayhoax/phpmaxbot without Composer

On this page you can find all versions of the php package grayhoax/phpmaxbot. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Example code of grayhoax/phpmaxbot

Informations about the package phpmaxbot

PHPMaxBot

Привлекательное изображение для репозитория

PHP библиотека для создания ботов в мессенджере MAX. Поддерживает полное API MAX messenger и предоставляет удобный интерфейс для разработки ботов.

Особенности

⚠️ Важно: требования к webhook и режиму работы

С 25 мая 2026 года MAX прекращает поддержку приёма вебхуков по HTTP и самоподписных сертификатов. Все продакшн-боты должны принимать обновления по HTTPS с сертификатом от доверенного центра сертификации (Let's Encrypt, коммерческие CA и т.д.). Подписки с HTTP-URL или невалидным сертификатом перестанут работать.

Чтобы переключиться на новый URL или обновить подписку, используйте текущий метод Bot::createSubscription() — повторный вызов с тем же URL заменит её настройки.

Long Polling не подходит для production. Получение обновлений через getUpdates (long polling) ограничено по скорости запросов и сроку хранения событий на сервере MAX. Используйте его только при локальной разработке и отладке — в продакшене переключайтесь на Webhook.

Кратко:

Окружение Рекомендуемый режим Требования
Разработка / отладка Long Polling (CLI) —
Staging / Production Webhook HTTPS + доверенный сертификат

Требования

Установка

Через Composer

Вручную

  1. Клонируйте репозиторий:

  2. Подключите автозагрузку:

Быстрый старт

Основное использование

Создание бота

Обработка команд

Обработка событий

Обработка callback-кнопок

Обработка входящих вложений

Когда пользователь нажимает кнопку requestContact или requestGeoLocation — или отправляет медиафайл — бот получает событие message_created с вложением (attachment). Используйте onAttachment($type, $handler) для обработки конкретного типа.

Обработчик получает полный массив вложения $attachment. Расположение данных зависит от типа:

Тип Данные в payload Прямые поля вложения
image photo_id, token, url —
video url, token —
audio url, token —
file url, token filename, size
sticker url, code width, height
contact vcf_info, max_info —
inline_keyboard buttons —
share url —
location нет latitude, longitude

Обработчики onAttachment срабатывают раньше общего on('message_created'). Для каждого типа регистрируется один обработчик.

Создание клавиатур

Типы кнопок

Отправка медиафайлов

PHPMaxBot предоставляет три уровня API для работы с файлами — от одного вызова до полного ручного контроля.

⚠️ Ограничения MAX на состав вложений

Сервер MAX накладывает жёсткое ограничение на вложения типа file:

В одном сообщении может быть только одно вложение типа file, и рядом с ним не может быть никаких других вложений, кроме inline_keyboard.

Состав сообщения Результат
1 × image ✅
несколько image / video / audio в любом сочетании ✅
1 × file ✅
1 × file + inline_keyboard ✅
2 × file ❌ 400 proto.payload
file + image (или video / audio / location / share) ❌ 400 proto.payload

Ответ сервера при нарушении:

Библиотека проверяет состав вложений до обращения к API и бросает MaxBotException с понятным текстом — так ошибка не превращается в «сообщение просто не пришло». Чтобы отправить смешанный набор, используйте Bot::sendAttachmentsToChat(), который сам разложит его на допустимые сообщения.

⚠️ Файл обрабатывается асинхронно

MAX принимает загрузку файла раньше, чем заканчивает его обработку. Сообщение, отправленное сразу после Bot::upload('file', ...), отклоняется:

Библиотека обрабатывает это сама: при получении attachment.not.ready отправка автоматически повторяется с линейно растущей паузой. Поведение настраивается:

Если повторы исчерпаны, бросается ApiException с кодом attachment.not.ready.

Как это работает

Загрузка файла в MAX состоит из двух шагов: сначала запрашивается URL загрузки, затем файл передаётся на этот URL. Способ получения токена вложения зависит от типа файла:

Тип Шаг 1 uploadFile() Шаг 2 uploadFileToUrl() Откуда токен
image, file возвращает только url передаёт файл → возвращает token из ответа шага 2
video, audio возвращает url и token передаёт файл (слот завершается) из ответа шага 1

Все высокоуровневые методы скрывают эту разницу — вы просто передаёте файл.

Уровень 1 — высокоуровневые методы (рекомендуется)

Один вызов: библиотека сама получает URL, загружает файл и отправляет сообщение.

Отправка в чат

Отправка пользователю

Сигнатура методов

Параметр $extra принимает те же опции, что и sendMessageToChat() / sendMessageToUser() (format, дополнительные attachments и т.д.).

Уровень 2 — получение токена, ручная отправка

Используйте этот вариант, когда нужен токен до отправки сообщения — например, чтобы вложить файл в ответ на callback.

⚠️ Частая ошибка: положить в одно сообщение и картинку, и файл. MAX ответит 400 proto.payload — библиотека перехватит это раньше и бросит MaxBotException.

Пакетная отправка нескольких вложений

Когда нужно отправить сразу несколько вложений, из которых часть — файлы, используйте sendAttachmentsToChat() / sendAttachmentsToUser(). Метод сам разложит набор на допустимые сообщения: все не-файловые вложения уходят одним сообщением, каждый файл — отдельным.

Элемент набора описывается ключами:

Ключ Обязателен Описание
type да image, video, audio, file
path да¹ путь к локальному файлу — будет загружен автоматически
token да¹ готовый токен, если файл уже загружен через Bot::upload()
mime нет MIME-тип; по умолчанию определяется по расширению

¹ нужно указать либо path, либо token.

Подпись ($caption) ставится на первое сообщение, а $extra['attachments'] (обычно клавиатура) — на последнее:

Сигнатуры:

Уровень 3 — полный ручной контроль

Когда нужен доступ к сырым ответам каждого шага.

image / file — токен из ответа на загрузку

video / audio — токен из первого ответа

Полный пример: бот с командами /photo и /video

Смотрите также пример examples/media-bot.php.

API методы

Сообщения

⚠️ Сообщение с вложением file не может содержать других вложений, кроме inline_keyboard — см. «Ограничения MAX на состав вложений». sendMessageToChat(), sendMessageToUser() и editMessage() проверяют это до обращения к API и бросают MaxBotException.

Чаты

Закрепленные сообщения

Бот

Видео

Подписки (Webhook)

С 25.05.2026 URL обязан быть HTTPS с сертификатом от доверенного CA. Запросы на HTTP-адреса и адреса с самоподписными сертификатами будут отклоняться.

Загрузка и отправка файлов (краткий справочник)

Полное описание — в разделе «Отправка медиафайлов». Ограничения на состав вложений — «Ограничения MAX на состав вложений».

Действия

Callback ответы

Формат сообщений

Подробнее про форматирование

Запуск бота

PHPMaxBot::start() сам определяет режим:

Long Polling (только для разработки)

Бот опрашивает getUpdates в цикле. Подходит для локальной отладки.

⚠️ Long Polling не подходит для production. Метод getUpdates ограничен по скорости и сроку хранения событий — при нагрузке часть обновлений может быть пропущена. На staging и production используйте Webhook.

Webhook (production)

Требования:

  1. Публичный URL по HTTPS (HTTP больше не поддерживается с 25.05.2026).
  2. Сертификат от доверенного центра (Let's Encrypt, ZeroSSL, коммерческие CA). Самоподписные сертификаты больше не поддерживаются.
  3. Скрипт должен отвечать на POST-запросы от MAX и возвращать 2xx.

Минимальный webhook-скрипт (например, public/webhook.php):

Регистрация webhook (выполняется один раз — отдельным скриптом или из админки):

Готовый пример: examples/webhook-bot.php.

Обновление подписки

Чтобы сменить URL или список событий — просто вызовите createSubscription повторно с новым URL (старую при необходимости удалите через deleteSubscription):

Проверка SSL-сертификата при исходящих запросах

По умолчанию библиотека отключает CURLOPT_SSL_VERIFYPEER / CURLOPT_SSL_VERIFYHOST для исходящих запросов к API MAX (это удобно при разработке). В production обязательно включите проверку — см. раздел «Настройка параметров cURL»:

Обработка исключений

Ошибки внутри обработчиков

Исключение, вылетевшее из обработчика, перехватывается фреймворком и передаётся в лог, а не в ответ HTTP: тело ответа на webhook MAX отбрасывает, поэтому ошибка, выведенная туда через echo, исчезла бы бесследно — со стороны это выглядит как «бот молча ничего не отправил».

Поведение по режимам:

Режим Что происходит с ошибкой обработчика
Webhook пишется в лог, вебхуку возвращается 200 (чтобы MAX не повторял заведомо падающий запрос)
Long Polling пишется в лог и в консоль; обработка остальных обновлений продолжается

По умолчанию сообщения уходят в error_log(). Свой обработчик:

В строку лога попадают класс исключения, текст, а для ApiException — ещё и код ошибки MAX с HTTP-статусом и контекстом:

Доступ к текущему обновлению

Типы обновлений

Доступные типы обновлений для фильтрации:

Структура обновлений: получение userId и chatId

Разные типы обновлений имеют разную структуру. Пути к идентификаторам:

Тип обновления userId chatId
message_created $update['message']['sender']['user_id'] $update['message']['recipient']['chat_id'] ¹
message_edited $update['message']['sender']['user_id'] $update['message']['recipient']['chat_id'] ¹
message_callback $update['callback']['sender']['user_id'] $update['callback']['message']['recipient']['chat_id'] ¹
message_removed $update['user_id'] $update['chat_id']
bot_started $update['user']['user_id'] $update['chat_id']
bot_stopped $update['user']['user_id'] $update['chat_id']
bot_added $update['user']['user_id'] $update['chat_id']
bot_removed $update['user']['user_id'] $update['chat_id']
user_added $update['user']['user_id'] $update['chat_id']
user_removed $update['user']['user_id'] $update['chat_id']
chat_title_changed $update['user']['user_id'] $update['chat_id']
dialog_removed $update['user']['user_id'] $update['chat_id']

¹ Поле chat_id в объекте recipient присутствует только для групповых чатов. В личном диалоге оно отсутствует — для ответа используйте sender.user_id.

Примеры:

Указать типы обновлений:

Примеры

Файл Что демонстрирует
sample.php Полный пример с командами, клавиатурами и вложениями
examples/simple-bot.php Команды, события, регулярные выражения
examples/keyboard-bot.php Inline-клавиатуры, callback-кнопки, запрос контакта и геолокации
examples/attachments-bot.php Обработка всех типов входящих вложений через onAttachment()
examples/media-bot.php Отправка изображений, видео, аудио и файлов
examples/webhook-bot.php Production-режим: HTTPS webhook + регистрация подписки

Запуск любого примера:

Debug режим

Настройка параметров cURL

Библиотека позволяет задать любые параметры cURL, которые будут применяться к каждому запросу к API.

Защищённые параметры — CURLOPT_URL, CURLOPT_RETURNTRANSFER, CURLOPT_CUSTOMREQUEST, CURLOPT_HTTPHEADER, CURLOPT_POSTFIELDS — всегда устанавливаются библиотекой и не могут быть переопределены.
SSL-параметры (CURLOPT_SSL_VERIFYHOST, CURLOPT_SSL_VERIFYPEER) по умолчанию отключены, но могут быть переопределены.

Способ 1: через второй параметр конструктора (рекомендуется)

Способ 2: через статическое свойство (можно менять в любой момент)

Примеры конфигураций

Работа через прокси:

Строгая проверка SSL (для продакшн-среды):

Ограничение таймаутов:

Лицензия

GPL-3.0

Автор

GrayHoax [email protected]

Ссылки

Поддержка

Если у вас возникли проблемы или вопросы, создайте issue на GitHub.

All versions of phpmaxbot with dependencies

PHP Build Version
Package Version
Requires php Version >=7.4
ext-curl Version *
ext-json Version *
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package grayhoax/phpmaxbot contains the following files

Loading the files please wait ...