Подключение к платформе MAX для партнёров и её сервисам — чат-ботам, мини-приложениям, каналам — доступно для юрлиц, ИП и самозанятых, которые являются резидентами РФ. Подключение к сервису Цифрового ID доступно только для юрлиц и ИП (резидентов РФ) С навыками разработки вы можете создавать чат-ботов с неограниченным потенциалом и возможностью размещать мини-приложения в MAX Вы можете [создать бота](/docs/chatbots/bots-create/create), только если у вас есть [верифицированный профиль организации, ИП или самозанятого](/docs/maxbusiness/connection#Верификация) на платформе MAX для партнёров. Количество доступных для создания ботов зависит от типа профиля Пользователи могут получить доступ к боту после его успешной модерации. [Статус модерации](/docs/chatbots/bots-create/create#Статусы%20модерации) отображается рядом с названием бота Собрать сценарий для бота можно без кода, для этого есть конструкторы с набором готовых решений. Подробнее [в разделе «Конструктор сценариев: без кода»](/docs/chatbots/bots-nocode) ## Отправка API-запросов API — это сервис, который позволяет взаимодействовать с платформой от имени бота. Бот отправляет запросы с токеном к [API MAX](/docs-api) и получает обновления с сервера в формате JSON Так выглядит базовый запрос к API MAX: https://platform-api2.max.ru/me? Authorization: В ответ вернётся информация о боте — его имя, токен или никнейм Для стабильной работы ботов убедитесь, что максимальное количество запросов в секунду на `platform-api2.max.ru` — 30 rps Подробнее о работе с сервером, методах и параметрах запросов читайте [в разделе про API](/docs-api) Если вы пишете ботов на TypeScript, JavaScript или Golang, рекомендуем использовать нашу официальную библиотеку — она содержит разные стандартные методы и утилиты. Читайте подробнее в разделах [«Библиотека JavaScript»](/docs/chatbots/bots-coding/js) и [«Библиотека Golang»](/docs/chatbots/bots-coding/go) здесь или на GitHub Перейти в репозиторий библиотеки на Typescript Перейти в репозиторий библиотеки на Go Вы можете воспользоваться Golang-фреймворком, чтобы с его помощью настраивать бота, обрабатывать сообщения, команды, callback-запросы и события Перейти в репозиторий Golang-фреймворка ## Настройка уведомлений - В целях повышения безопасности **с 25 мая** прекращается поддержка получения вебхуков по HTTP, а также самоподписных сертификатов. Рекомендуем заранее перейти на HTTPS и сертификаты от доверенных центров, в том числе сертификаты Минцифры. Чтобы обновить подписку на события, используйте [POST /subscriptions](/docs-api/methods/POST/subscriptions) - Получение обновлений с помощью [Long Polling](/docs-api/methods/GET/updates) ограничено по скорости и сроку хранения событий — этот способ не подходит для production-окружения. Рекомендуем на всех этапах работы использовать [Webhook](/docs-api/methods/POST/subscriptions) API поддерживает два типа уведомлений о действиях пользователей с ботом — выбор зависит от этапа работы: - Для **production-окружения — только Webhook** - Для разработки и тестирования — Webhook или Long Polling Использовать одновременно оба типа нельзя — выберите один из них Технологии отправки уведомлений отличаются способом взаимодействия с сервером и продолжительностью отклика. Webhook после новых действий в чат-боте сам отправляет запрос на сервер, а Long Polling работает методом периодических запросов без триггера в боте **Webhook** Чтобы получить обновления о событиях через Webhook, отправьте [POST-запрос `/subscriptions`](/docs-api/methods/POST/subscriptions). В запросе укажите URL, на который должна приходить информация о новых событиях с ботом Чтобы получить список всех подписок на обновления через Webhook, отправьте [GET-запрос `/subscriptions`](/docs-api/methods/GET/subscriptions) - Для повышения безопасности **с 25 мая** прекращается поддержка получения вебхуков по HTTP, а также самоподписных сертификатов. Используйте HTTPS и сертификаты, выданные доверенным центром сертификации, в том числе сертификаты Минцифры. Подробнее о требованиях безопасности при подключении вебхуков — [в описании POST /subscriptions](/docs-api/methods/POST/subscriptions) - Для стабильной работы ботов убедитесь, что максимальное количество запросов на `platform-api2.max.ru` — 30 rps **Long Polling** Получение обновлений с помощью [Long Polling](/docs-api/methods/GET/updates) ограничено по скорости и сроку хранения событий — этот способ не подходит для production-окружения. Рекомендуем на всех этапах работы использовать [Webhook](/docs-api/methods/POST/subscriptions) Чтобы получить обновления через Long Polling, выполните [GET-запрос `/updates`](/docs-api/methods/GET/updates) ## Работа с диплинками Диплинки (deep links) — это специальные ссылки, которые позволяют открывать чат-ботов MAX с передачей дополнительных параметров. С их помощью можно передавать контекстную информацию, отслеживать источники переходов или автоматически выполнять определённые действия при запуске ### Создание диплинка бота Чтобы создать диплинк бота, используйте следующий формат ссылки: https://max.ru/?start= Где: - `` — никнейм бота - `` — дополнительные данные (до 128 символов) Если `payload` превышает 128 символов, он не будет передан боту **Примеры** Базовая ссылка https://max.ru/SupportBot?start=123 Реферальная ссылка https://max.ru/MyBot?start=ref_user456789 Отслеживание источника https://max.ru/NewsBot?start=source_site ### Payload в боте #### Как получить payload в боте Для получения обновлений с `payload` бот должен использовать **Webhook** или **Long Polling** Получение обновлений с помощью [Long Polling](/docs-api/methods/GET/updates) ограничено по скорости и сроку хранения событий — этот способ не подходит для production-окружения. Рекомендуем на всех этапах работы использовать [Webhook](/docs-api/methods/POST/subscriptions) При настройке Webhook убедитесь, что в параметре `update_types` включён тип `bot_started`. Подробнее о событиях в боте — [в описании объекта `Update`](/docs-api/objects/Update#Типы%20событий) Когда пользователь переходит по диплинку, бот получает обновление типа `bot_started` через Webhook или Long Polling в [объекте `Update`](/docs-api/objects/Update#Типы%20событий): { "update_type": "bot_started", "timestamp": 1573226679188, "chat_id": 1234567890, "user": { "user_id": 1234567890, "name": "Иван", "username": "ivan_petrov" }, "payload": "promo_summer2025" } Ключевые поля в [объекте `Update`](/docs-api/objects/Update#Типы%20событий): - `update_type` — всегда `bot_started` при запуске бота через диплинк - `payload` — переданное значение из URL (может быть `null`, если параметр не указан) - `user` — информация о пользователе, который запустил бота - `chat_id` — ID чата #### Можно ли передать несколько параметров в payload Для получения несколько параметров в `payload` их нужно закодировать в одну строку, например: ?start=param1_value1_param2_value2 ### Запуск бота через диплинк из внешнего приложения Вы можете перенаправить пользователя из вашего приложения или лендинга прямо в бота MAX, передав через диплинк необходимый контекст: идентификатор пользователя, номер заказа, промокод и так далее **Как происходит перенаправление пользователя в бота по диплинку**: 1. Вы формируете диплинк для перехода в бота, передав в `payload` необходимые параметры. Убедитесь, что длина `payload` не превышает 128 символов 2. Вы добавляете в приложение или на лендинг кнопку с диплинком 3. Пользователь переходит по диплинку и запускает бота в MAX 4. Бот получает событие `bot_started` и извлекает `payload` 5. Бот обрабатывает `payload` и отображает информацию в соответствии с переданными параметрами Не передавайте в `payload` конфиденциальные данные в открытом виде — используйте одноразовые токены или закодированные идентификаторы сессии **Примеры диплинков для перехода в бот** | Сценарий | Пример диплинка | Пример использования | | -------- | --------------- | -------------------- | | Обратная связь о посещении ресторана | `https://max.ru/MyBot?start=feedback_rest123` | Вы размещаете QR-код на чеке или на столике. Пользователь сканирует QR-код, переходит в бота MAX по диплинку. Бот отображает диалоговое окно с предложением оценить обслуживание или оставить отзыв о блюдах | | Получение промокода на скидку | `https://max.ru/MyBot?start=promo123` | Вы добавляете ссылку для перехода в бот в рассылку. Пользователь переходит в бота MAX и видит диалоговое окно с приветствием и промокодом на скидку | | Отслеживание источника переходов в бот | `https://max.ru/MyBot?start=your_site` | Вы размещаете ссылки для перехода в бот на внешних сайтах и отслеживаете статистику переходов с каждого ресурса | | Отслеживание статуса заказа | `https://max.ru/MyBot?start=order_12345` | Вы размещаете ссылку для отслеживания заказа на сайте своего ресторана. Пользователь переходит в бота MAX по диплинку с номером заказа. Бот получает идентификатор заказа и сразу показывает актуальный статус и дополнительную информацию по доставке | Важно! Диплинки нужны для запуска чат-бота и передачи контекста. Их использование не должно противоречить [требованиям](/docs/legal/requirements) к содержанию и функциональности приложений. Например, отправлять авторизационные сообщения через диплинки запрещено Если у вас возникли вопросы, [посмотрите раздел с ответами](/help)