Возможности Telegram Ботов: Полное руководство с примерами и советами

Задумывались ли вы, почему Telegram боты стали такими популярными? Возможно, потому что они умеют практически всё: от отправки сообщений до управления бизнесом или запуска HTML5 игр. Если вы знаете английский, то можете заглянуть в официальную документацию Telegram, но мы подготовили для вас максимально понятное и увлекательное руководство на русском языке. Здесь вы найдёте всё: от базовых вещей до продвинутых фишек, которые заставят вашего бота работать как часы. Ну а если вы любите программировать на PHP, то вам точно понравится!

Вводные данные

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

Команды, которые выделяются в сообщениях и могут быть выбраны из списка после ввода /.
Клавиатуры, которые заменяют клавиатуру пользователя заранее определенными вариантами ответов.
Кнопки, которые отображаются рядом с сообщениями от бота.

Для еще большей гибкости Веб-приложения поддерживают 100% пользовательские интерфейсы с использованием JavaScript.

Примечание: Боты Telegram могут поддерживать несколько языков, которые адаптируются к языковым настройкам пользователей в приложении.

Команды

Команда — это простой /keyword, который говорит боту, что делать. Приложения Telegram будут:

Выделять команды в сообщениях. Когда пользователь нажимает на выделенную команду, эта команда немедленно отправляется снова.
Предлагать список поддерживаемых команд с описаниями, когда пользователь вводит / (для этого необходимо предоставить список команд @BotFather или через соответствующий метод API). Выбор команды из списка немедленно отправляет её.
Показывать кнопку меню, содержащую все или некоторые команды бота (которые вы задаете через @BotFather).

Команды всегда должны начинаться с символа / и содержать до 32 символов. Они могут использовать латинские буквы, цифры и подчеркивания, хотя для более аккуратного вида рекомендуется использовать простой текст в нижнем регистре.

Вот несколько примеров:

/next
/cancel
/newlocation
/newrule

Команды должны быть как можно более конкретными – например, /newlocation или /newrule лучше, чем команда /new, которая затем требует от пользователя дополнительный параметр, такой как "location“ или ”rule".

Мы требуем, чтобы все разработчики поддерживали несколько Глобальных Команд, чтобы обеспечить согласованный и удобный для пользователя опыт работы с Telegram ботами.

Области применения команд

Ваш бот может показывать разные команды разным пользователям и группам – вы можете контролировать это с помощью областей применения. Например, ваш бот может показывать дополнительные команды администраторам групп или переводить список в зависимости от языкового кода пользователя.

Имейте в виду, что обновления Bot API не будут содержать никакой информации об области применения команды, отправленной пользователем – на самом деле, они могут содержать команды, которые вообще не существуют в вашем боте. Ваш бэкенд должен всегда проверять, что полученные команды действительны и что пользователь был уполномочен их использовать, независимо от области применения.

Боты с включенным режимом конфиденциальности будут получать команды в группах только при особых условиях, см. здесь.

Клавиатуры

Боты могут интерпретировать свободный текст, вводимый пользователями, но предоставление конкретных предложений часто бывает более интуитивным – здесь пользовательские клавиатуры могут быть крайне полезны.

Каждый раз, когда ваш бот отправляет сообщение, он может отобразить специальную клавиатуру с заранее определенными вариантами ответа (см. ReplyKeyboardMarkup). Приложения Telegram, получающие сообщение, отобразят вашу клавиатуру пользователю. Использование любой из кнопок немедленно отправит соответствующий текст. Таким образом, вы можете значительно упростить и оптимизировать взаимодействие пользователя с вашим ботом.

Посмотрите параметр one_time_keyboard, чтобы автоматически скрывать клавиатуру вашего бота, как только она была использована.

Вы также можете настроить текст-заполнитель в поле ввода, установив параметр input_field_placeholder.

Встраиваемые клавиатуры

Иногда вы можете предпочесть делать вещи без отправки сообщений в чат – например, когда пользователь изменяет настройки, переключает опции или просматривает результаты поиска. В таких случаях вы можете использовать встраиваемые клавиатуры, которые отображаются непосредственно под соответствующими сообщениями.

В отличие от пользовательских клавиатур с ответами, нажатие кнопок на встраиваемых клавиатурах не отправляет сообщения в чат. Вместо этого встраиваемые клавиатуры поддерживают кнопки, которые могут работать за кулисами или открывать различные интерфейсы: callback-кнопки, URL-кнопки, кнопки переключения на встраиваемые, игровые кнопки и кнопки оплаты.

Чтобы обеспечить лучший пользовательский опыт, рассмотрите возможность редактирования вашей клавиатуры, когда пользователь переключает кнопку настройки или переходит на новую страницу – это быстрее и плавнее, чем отправка нового сообщения и удаление предыдущего.

Кнопка меню

Во всех чатах бота кнопка меню появляется рядом с полем для сообщений. По умолчанию нажатие этой кнопки открывает меню, которое может содержать некоторые или все команды бота, включая краткое описание для каждой. Пользователи могут выбрать команду из меню без необходимости вводить её вручную.

Вы можете установить разные тексты кнопки меню и её описания команд для различных отдельных пользователей или групп пользователей – например, показывая переведённый текст в зависимости от языка пользователя, как объясняется здесь.

Кнопка меню также может быть использована для запуска Web App.

Глобальные команды

Чтобы сделать базовые взаимодействия более унифицированными, мы просим всех разработчиков поддерживать несколько базовых команд. В приложениях Telegram будут доступны интерфейсные ярлыки для этих команд.

/start - начинает взаимодействие с пользователем, например, отправляя приветственное сообщение. Эта команда также может быть использована для передачи дополнительных параметров боту (см. Глубокая привязка).
/help - возвращает сообщение с помощью, например, краткий текст о том, что может делать ваш бот, и список команд.
/settings - (если применимо) показывает настройки бота для этого пользователя и предлагает команды для их редактирования.

Пользователи увидят кнопку Начать в первый раз, когда откроют чат с вашим ботом. Ссылки Помощь и Настройки будут доступны в меню на странице профиля бота, если вы добавите их в @BotFather.

Выбор чатов и пользователей

Боты могут предоставить пользователю дружелюбный и интуитивно понятный интерфейс, который отображает любое количество групп, каналов или других пользователей в соответствии с заданным набором критериев. Нажатие на чат отправит его идентификатор боту в служебном сообщении и плавно закроет интерфейс.

Бот для управления группами является идеальным примером: администратор может выбрать чат, который бот должен управлять, а затем выбрать пользователя, которого он должен повысить – это произойдет без необходимости вводить какой-либо текст.

Вот руководство по быстрому старту для использования этой функции:

Выберите набор критериев и сохраните их в объекте KeyboardButtonRequestChat (или KeyboardButtonRequestUser для пользователей).
Создайте KeyboardButton и сохраните критерии в request_chat или request_user соответственно.
Отправьте ReplyKeyboardMarkup, который содержит только что созданную кнопку.
Когда пользователь выберет чат, вы получите его идентификатор в служебном сообщении chat_shared или user_shared.

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

Взаимодействия

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

Инлайн-режим позволяет отправлять запросы к ботам прямо из поля ввода – из любого чата в Telegram.
Глубокая ссылка позволяет использовать специальные ссылки, которые отправляют определенные параметры боту при открытии.
Меню вложений интеграция делает возможным использование ботов из меню вложений в чатах.

Инлайн-запросы

Пользователи могут взаимодействовать с вашим ботом через инлайн-запросы прямо из поля сообщения в любом чате. Все, что им нужно сделать, это начать сообщение с вашего @username и ввести ключевое слово.

Получив запрос, ваш бот может вернуть некоторые результаты. Как только пользователь выберет один из них, он отправляется в соответствующий чат. Таким образом, люди могут запрашивать и отправлять контент от вашего бота в любых своих чатах, группах или каналах.

Не забывайте, что инлайн-функциональность должна быть включена через @BotFather, иначе ваш бот не будет получать инлайн обновления.

Примеры инлайн-ботов включают @gif, @bing и @wiki. Боты Web App также могут использоваться инлайн – попробуйте ввести @durgerkingbot в любом чате.

Глубокая ссылка

Боты Telegram имеют механизм глубоких ссылок, который позволяет передавать дополнительные параметры боту при запуске. Это может быть команда, которая запускает бота, или токен аутентификации для подключения учетной записи Telegram пользователя к его учетной записи на другой платформе.

Каждый бот имеет ссылку, которая открывает разговор с ним в Telegram – https://t.me/<bot_username>. Параметры можно добавить непосредственно к этой ссылке, чтобы ваш бот мог работать с дополнительной информацией на лету, без ввода от пользователя.

Допустимы символы A-Z, a-z, 0-9, _ и -. Мы рекомендуем использовать base64url для кодирования параметров с двоичными и другими типами содержимого. Параметр может содержать до 64 символов.

Личные чаты
В личных чатах вы можете использовать параметр start, чтобы автоматически передавать любое значение вашему боту, когда пользователь нажимает на ссылку. Например, вы можете использовать:

https://t.me/your_bot?start=airplane

Когда кто-то открывает чат с вашим ботом по этой ссылке, вы получите:

/start airplane

Группы
В группах вы можете добавить параметр startgroup к этой ссылке. Например:

https://t.me/your_bot?startgroup=spaceship

Переход по ссылке с этим параметром предлагает пользователю выбрать группу, в которую добавить бота – полученное обновление будет содержать текст в следующем виде:

/start@your_bot spaceship

Веб-приложения также поддерживают глубокие ссылки, для получения дополнительной информации ознакомьтесь с нашим специальным руководством.

Меню вложений

Некоторые боты могут быть добавлены непосредственно в меню вложений пользователя, что обеспечивает легкий доступ к боту в любом чате. В настоящее время эта опция ограничена определенными одобренными ботами, но может быть расширена в будущем.

Попробуйте добавить @DurgerKingBot в ваше меню вложений.

Интеграция

Существует множество способов дальнейшей интеграции ботов с Telegram и другими сервисами.

Используйте Web Apps, чтобы заменить любой веб-сайт.
Создавайте инструменты и интегрируйте бизнес-сервисы.
Принимайте Платежи через сторонних поставщиков платежей, которые поддерживают интеграцию с Ботами и Мини-приложениями.
Подключайтесь к Telegram с помощью функциональности Web Login.
Создавайте игровые боты, интегрируя HTML5 Игры.
Помогайте пользователям создавать и управлять Telegram Наклейками.

Монетизация

Telegram предлагает мощную экосистему функций монетизации, позволяя любому боту поддерживать свое развитие с помощью нескольких источников дохода.

Телеграм Звезды

Телеграм Звезды являются основой всех цифровых транзакций между ботами и пользователями. Пользователи могут приобрести Звезды через внутренние покупки в приложении через Apple и Google или через @PremiumBot.

Боты могут использовать полученные Звезды для увеличения лимитов сообщений, отправки подарков пользователям или приема вознаграждений в Toncoin.

Цифровые продукты

Сервисы могут использовать своего бота для продажи цифровых товаров и услуг – таких как онлайн-курсы, заказные произведения искусства и предметы в играх.

Платные медиа

Боты могут публиковать платные фотографии и видео – и пользователи могут просматривать медиа только после оплаты для его разблокировки. Эта функциональность доступна для всех ботов – включая администраторов ботов в каналах и ботов, управляющих Telegram Business аккаунтами.

Планы подписки

Разработчики могут предлагать платные подписки на своего бота – добавляя несколько уровней контента и функций, адаптированных под свою аудиторию.

Доля дохода от рекламы в Telegram

Разработчики могут участвовать в распределении дохода от рекламы в Telegram – получая 50% от дохода от рекламы, которая появляется в чате с их ботом.

Мини-приложения

Мини-приложения позволяют разработчикам создавать бесконечно гибкие интерфейсы, которые можно запускать прямо внутри Telegram – безшовно интегрируясь с приложением и заменяя любой веб-сайт.

Если ваш бот является мини-приложением, вы можете добавить заметную кнопку Запустить приложение, а также демонстрационные видео и скриншоты в профиль бота. Для этого перейдите к @BotFather и настройте Основное мини-приложение вашего бота.

Мини-приложения подробно описаны в нашем посвященном руководстве – вам стоит внимательно его прочитать, чтобы узнать о широком разнообразии функций, которые они могут предложить.

Если вы разрабатываете мини-приложение, обязательно следуйте нашим руководящим принципам дизайна – вы захотите, чтобы ваш пользовательский интерфейс бесшовно интегрировался в приложение, чтобы предоставить пользователям наилучший опыт.

Бесшовная интеграция с Telegram

Мини-приложения интегрируются бесшовно с Telegram – от получения подробных настроек темы до использования нативных диалогов для чтения QR-кодов, управления биометрией, обмена медиа непосредственно в историях и многого другого.

Когда мини-приложения открываются по прямой ссылке в группе, они также могут использовать параметр chat_instance для отслеживания текущего контекста, поддерживая совместное использование несколькими участниками чата – для создания живых белых досок, групповых заказов, многопользовательских игр и многого другого.

Предварительный просмотр мини-приложений

Разработчики могут загружать скриншоты и видео-демонстрации своих мини-приложений прямо со страницы профиля бота – предоставляя пользователям обзор возможностей и функциональности приложения. Эти медиа-превью будут показаны любому пользователю, который просматривает ваше приложение – например, в Мини Магазине Приложений или через Поиск.

Предварительные просмотры поддерживают несколько языков – поэтому вы можете загружать переведенные версии ваших превью, которые будут показаны пользователям в зависимости от их языка приложения.

Магазин мини-приложений

Более 500 миллионов из 950 миллионов пользователей Telegram взаимодействуют с мини-приложениями каждый месяц. Успешные мини-приложения имеют шанс быть выделенными в Магазине мини-приложений Telegram – появляясь для всех пользователей во вкладке 'Приложения' поиска.

Выделенные мини-приложения выбираются на основе того, как они обогащают экосистему Telegram. Чтобы увеличить шансы на выделение, вы должны включить Главное мини-приложение в @BotFather, загрузить качественные медиа-демонстрации, демонстрирующие ваше приложение, в профиль вашего бота и принимать платежи в Telegram Stars.

Посмотрите нашу документацию, чтобы узнать больше о включении главных мини-приложений и приеме платежей в Stars.

Ссылки на главном экране

Пользователи могут размещать прямые ссылки на конкретные мини-приложения на главном экране своих устройств – получая доступ к любимым играм и сервисам в один клик.

Настраиваемые экраны загрузки

Экран загрузки мини-приложений можно настроить в @Botfather – где разработчики могут добавить свой собственный значок и установить определенные цвета как для светлой, так и для темной тем.

Чтобы настроить экран загрузки, перейдите в @Botfather > /mybots > Выберите бота > Настройки бота > Настроить мини-приложение > Настроить экран загрузки. Вы можете нажать на Открыть предварительный просмотр экрана загрузки, чтобы увидеть конечный результат.

Режим полного экрана

Мини-приложения могут использовать весь экран в портретной или ландшафтной ориентации – что позволяет создавать погружающие игры и медиа с расширенными жестами и интерфейсами.

Настройка Emoji Статуса

Пользователи могут установить emoji статус внутри мини-приложений или предоставить приложению разрешение на автоматическое обновление.

Разработчики также могут интегрировать API других сервисов или запросить доступ к геолокации – мгновенно изменяя статус пользователя, когда он начинает игру или покидает офис .

Обмен медиа

Медиа, созданные в мини-приложениях, могут быть поделены в любом чате – позволяя пользователям легко отправлять реферальные коды и кастомные изображения контактам, группам и каналам. В качестве альтернативы, пользователи могут скачать их с помощью нативного всплывающего окна.

Поделитесь из мини-приложений в истории

Любые медиа, созданные мини-приложением, такие как снимки с белой доски, таблицы лидеров и видео, созданные ИИ, могут быть открыты с помощью встроенного редактора историй через метод shareToStory – чтобы пользователи могли поделиться ими как Telegram Историей прямо из мини-приложения.

Мини-приложения также получают ряд событий, позволяя им мгновенно реагировать на действия пользователя. Вы можете узнать больше о доступных событиях здесь.

Доступ к геолокации

Мини-приложения могут получать разрешения на использование местоположения от пользователей, что дает разработчикам возможность создавать игры на основе местоположения и интерактивные карты для мероприятий.

Отслеживание движения устройства

Мини-приложения могут запрашивать данные о ускорении, ориентации и вращении устройств в реальном времени – открывая поддержку для управления движением и VR-опыта.

Информация о аппаратном обеспечении устройства

Устройство пользователя может отправлять основную информацию об аппаратном обеспечении мини-приложениям, такую как его вычислительная мощность и объем памяти. Мини-приложения могут использовать это для оптимизации графики и автоматической регулировки настроек для обеспечения наилучшего опыта.

Боты для бизнеса

Боты могут включать Бизнес-режим, позволяя подписчикам Telegram Business подключать их к своему аккаунту – упрощая и автоматизируя управление частными чатами и взаимодействие с клиентами.

Владелец аккаунта может указать, к каким чатам ваш бот может получить доступ – в этих чатах бот будет получать все обновления, которые обычно поддерживаются Bot API, за исключением сообщений, отправленных им самим и другими ботами. В зависимости от настроек бизнес-соединения, ваш бот также может иметь возможность отправлять сообщения и выполнять другие действия от имени владельца аккаунта в чатах, которые были активны в последние 24 часа.

Вот краткое руководство по интеграции вашего бота с Telegram Business:

Включите Бизнес-режим для вашего бота в @BotFather.
Обрабатывайте входящие BusinessConnection обновления, сигнализируя о том, что пользователь установил, изменил или закрыл Бизнес-соединение с вашим ботом.
Обрабатывайте бизнес-сообщения, обрабатывая обновления business_message, edited_business_message и deleted_business_messages.
Проверьте разрешения на запись вашего бота через can_reply в последнем обновлении BusinessConnection.
Если это разрешено, используйте поле business_connection_id в sendMessage, sendChatAction и других методах отправки, чтобы общаться от имени бизнес-пользователя.

Пользователи, которые подключают вашего бота к своему аккаунту, увидят панель быстрого доступа в верхней части каждого управляемого чата – нажав на «Управлять ботом», они будут перенаправлены к вашему боту, который получит сообщение глубокой ссылки в формате /start bizChat<user_chat_id>.

Пожалуйста, имейте в виду, что работа с ботами в Telegram подчиняется Условиям обслуживания разработчиков ботов Telegram. В частности, для Telegram Business убедитесь, что вы прочитали и поняли раздел 5.4.

Платежи

Если ваш бот или мини-приложение продает цифровые товары и услуги, обязательно проводите оплату в Telegram Stars, указав XTR в качестве валюты. В соответствии с политикой сторонних магазинов, Telegram не поддерживает продажу цифровых товаров и услуг с использованием других валют.

Телеграм-боты могут принимать платежи с помощью стильного, упрощенного интерфейса, который собирает все необходимые данные от пользователя. Telegram не собирает никаких платежных данных – таких как информация о кредитной карте пользователя – и отправляет их напрямую одному из поддерживаемых сторонних поставщиков платежей.

Вот руководство по быстрому старту для реализации платежей:

Выберите поставщика и получите соответствующий токен, а также тестовый токен от поставщика "Stripe TEST MODE".
Реализуйте платежи через соответствующие методы API.
Проверьте вашу реализацию, используя ваш тестовый токен вместе с тестовой кредитной картой.

Затем, чтобы выставить счет и обработать процесс заказа:

Отправьте счет пользователю за товары или услуги, которые вы предлагаете.
Проверьте заказ и примите оплату через answerPreCheckoutQuery.
Подтвердите платеж, проверив наличие успешного сообщения о платеже.
Отправьте товары или предоставьте услуги.

Для получения более подробной информации вы можете ознакомиться с нашими полными исчерпывающими руководствами по продаже товаров и услуг в Telegram – они включают живые контрольные списки, параметры и подробные описания методов:

Telegram не обрабатывает платежи напрямую, не хранит данные о заказах и не взимает никаких сборов. Счета пересылаются напрямую стороннему поставщику платежей.
По этой причине споры должны решаться между пользователем, разработчиком бота и поставщиком платежей. Вы можете прочитать об этом в Политике конфиденциальности.

Веб-авторизация

Telegram предлагает гибкую, легковесную и бесплатную платформу для аутентификации пользователей на любом веб-сайте и в приложении. Это может быть использовано для связи вашей платформы с Telegram, обеспечивая вашим пользователям плавный опыт. Вы также можете свободно полагаться на эту платформу для реализации быстрого и безрегистрационного входа на вашем сайте, независимо от его связи с Telegram.

Виджеты

Виджет входа в Telegram — это простой и безопасный способ авторизации пользователей на вашем сайте.

Выберите бота — желательно, чтобы его имя и аватар соответствовали заголовку и логотипу сайта.
Используйте команду /setdomain в @BotFather, чтобы связать бота с доменом вашего сайта.
Настройте ваш виджет с помощью нашего специализированного инструмента и внедрите его на ваш сайт.

Инлайн Вход

Когда пользователи открывают ваш веб-сайт через инлайн кнопку, вы можете использовать параметр login_url в качестве альтернативы виджетам входа. Таким образом, вы сможете бесшовно авторизовать их на вашем веб-сайте или в приложении еще до загрузки страницы.

Не забудьте ознакомиться с нашим руководством по аутентификации полученных данных, а также с нашим примером кода.

HTML5 Игры

Боты могут служить независимыми игровыми платформами – с помощью нашего HTML5 Gaming API вы можете разрабатывать многопользовательские или одиночные игры и позволить вашим пользователям весело проводить время, сравнивая рейтинги, очки и многое другое.

Чтобы начать, выполните следующие простые шаги:

Отправьте команду /newgame @BotFather
Предоставьте текстовое описание, изображение или необязательный gif, чтобы продемонстрировать игровой процесс
Отправьте игру пользователям через метод sendGame или через инлайн-запрос
Когда кто-то захочет поиграть, вы получите соответствующее game_short_name в CallbackQuery
Чтобы запустить игру, предоставьте HTML5 Game URL в качестве параметра url метода answerCallbackQuery

Затем, чтобы обрабатывать рекорды:

Используйте setGameScore, чтобы публиковать высокие очки в чате с игрой
Используйте getGameHighScores, чтобы получить таблицы рекордов в игре

Вы также можете встроить кнопку поделиться в вашу игру, поэкспериментировать с пользовательскими инлайн-кнопками, URL-параметрами и многим другим. Чтобы лучше понять, обязательно ознакомьтесь с:

Посмотрите @GameBot и @gamee для примеров того, что вы можете сделать, используя нашу игровую платформу.

Стикерпаки и пользовательские эмодзи

Стикеры и Пользовательские эмодзи — это отличительная особенность Telegram, которой пользуются миллионы пользователей для обмена художественными работами каждый день. Стикеры и пользовательские эмодзи имеют множество форм — от простых изображений до плавных векторных анимаций и высокодетализированных .WEBM видео.

Все эти форматы поддерживаются нашим Bot API, который позволяет ботам создавать, редактировать, удалять и делиться новыми пакетами художественных работ на лету. Импорт API Telegram позволяет пользователям мигрировать пакеты с других платформ и приложений для стикеров.

Создание нового пакета
Чтобы создать новый пакет, просто:

Подготовьте свои художественные работы в соответствии с нашими техническими требованиями.
Создайте новый пакет стикеров через createStickerSet. Установите sticker_type на regular, чтобы создать пакет стикеров, или на custom emoji, чтобы создать пакет пользовательских эмодзи. Прикрепите файлы, которые вы хотите включить в пакет, в виде массива InputSticker.
Вы можете использовать addStickerToSet, чтобы добавить стикеры или эмодзи позже.

Дополнительные функции
Обычные стикеры и пользовательские эмодзи поддерживают ключевые слова, которые пользователи могут вводить, чтобы быстро находить соответствующие художественные работы — это может быть полезно, когда стикер не имеет очевидной связи с конкретным эмодзи. Вы можете использовать параметр keywords в InputSticker, чтобы указать их.

Пользовательские эмодзи дополнительно поддерживают адаптивные цвета — они всегда будут соответствовать текущему контексту (например, белый на фотографиях, акцентный цвет при использовании в статусе и т.д.); чтобы включить эту функцию, используйте параметр needs_repainting в createStickerSet.

Когда вы закончите создание и обмен своей художественной работой, не забудьте ознакомиться с нашими остальными методами стикеров, чтобы узнать, как редактировать, удалять и даже переставлять ваш пакет.

Обратите внимание, что эти методы будут работать только с пакетами, созданными ботом, который их вызывает.

Поддержка языков

Боты могут настраивать свои интерфейсы для поддержки нескольких языков – обновляя ввод и информацию на лету. language_code пользователя включен в каждое соответствующее обновление в качестве IETF language tag, что позволяет ботам адаптироваться соответственно.

Мы рекомендуем вам следовать нашим рекомендациям, чтобы предоставить лучший пользовательский опыт.

Ваши интерфейсы, тексты и инлайн-результаты должны бесшовно адаптироваться к language_code, без вмешательства пользователя.
Подключенные WebApps получат language_code пользователя – ваша HTML-страница должна учитывать это.
HTML5 игры могут получать информацию о языке, если вы укажете её в качестве параметра URL. Вы можете сгенерировать этот параметр из поля language_code в объекте User, который передается с первоначальным CallbackQuery игры.
Имя, Описание и Текст о боте могут быть локализованы с помощью соответствующих методов.
Списки команд также могут быть указаны для отдельных языков – подробнее об этом здесь.

language_code является необязательным полем – оно может быть пустым.
Если вы нацелены на широкую аудиторию, ваш код должен всегда возвращаться к последнему зафиксированному языковому тегу или английскому (в этом порядке), когда поле отсутствует для конкретного пользователя.

Управление ботами

Режим конфиденциальности

Боты часто добавляются в группы для выполнения базовых задач или помощи модераторам – например, для автоматической публикации объявлений компании или даже для поздравления с днями рождения. По умолчанию все боты, добавленные в группы, работают в режиме конфиденциальности и видят только соответствующие сообщения и команды:

Команды, явно предназначенные для них (например, /command@this_bot).
Общие команды (например, /start), если бот был последним ботом, отправившим сообщение в группу.
Инлайн-сообщения, отправленные через бота.
Ответы на любые сообщения, явно или неявно предназначенные для этого бота.

Все боты также будут получать, независимо от режима конфиденциальности:

Все служебные сообщения.
Все сообщения из личных чатов.
Все сообщения из каналов, в которых они являются участниками.

Режим конфиденциальности включен по умолчанию для всех ботов, кроме ботов, добавленных в группу в качестве администраторов (администраторы ботов всегда получают все сообщения). Его можно отключить, чтобы бот получал все сообщения, как обычный пользователь (боту потребуется быть повторно добавленным в группу, чтобы это изменение вступило в силу). Мы рекомендуем делать это только в случаях, когда это абсолютно необходимо для работы вашего бота. В большинстве случаев использование опции принудительного ответа для сообщений бота должно быть более чем достаточно.

Этот режим не только увеличивает конфиденциальность пользователей, но и делает бота более эффективным, уменьшая количество входных данных, которые ему необходимо обрабатывать. Пользователи всегда могут видеть текущие настройки конфиденциальности бота в списке участников группы.

Тестирование вашего бота

Вы можете быстро протестировать своего бота без вмешательства в его пользователей, просто запустив другой экземпляр вашего кода на другом аккаунте бота. Для этого создайте нового бота через @BotFather, получите его токен и используйте его в тестовом экземпляре вашего кода.

Все дальнейшие тестирования и отладка могут происходить в частном порядке на новом боте, не затрагивая оригинальный экземпляр.

Если вам нужно делиться ссылками на файлы между ботами, имейте в виду, что поле file_id привязано к одному идентификатору бота, поэтому ваш тестовый экземпляр не может использовать общую базу данных file_id для быстрого отправления медиа – файлы должны быть загружены заново индивидуально.

Выделенная тестовая среда

Telegram также предлагает выделенную тестовую среду, подходящую для более продвинутого тестирования. Боты и пользователи в этой среде, как правило, имеют более гибкие ограничения – например:

При работе с тестовой средой вы можете использовать HTTP-ссылки без TLS для тестирования ваших Web Apps или Web Login.

Ограничения на спам не повышаются в тестовой среде и могут быть временами более строгими. Чтобы минимизировать влияние этого на вашего бота, вы должны убедиться, что он обрабатывает ошибки с политиками повторных попыток и не зависит от жестко закодированных значений ограничений.

Создание бота в тестовой среде

Тестовая среда полностью отделена от основной среды, поэтому вам нужно будет создать новую учетную запись пользователя и нового бота с помощью @BotFather.

Чтобы создать учетную запись и войти в систему, используйте один из следующих способов:

iOS: нажмите 10 раз на иконку Настройки > Учетные записи > Войти в другую учетную запись > Тест.
Telegram Desktop: откройте ☰ Настройки > Shift + Alt + Щелчок правой кнопкой мыши 'Добавить учетную запись' и выберите 'Тестовый сервер'.
macOS: нажмите на иконку Настройки 10 раз, чтобы открыть меню отладки, ⌘ + щелкните 'Добавить учетную запись' и войдите с помощью номера телефона.

После входа в систему просто создайте нового бота, следуя стандартной процедуре, и отправляйте ваши запросы к Test Bot API в следующем формате:

https://api.telegram.org/bot<token>/test/METHOD_NAME

При работе с тестовой средой вы можете использовать HTTP-ссылки без TLS в поле url как для LoginUrl, так и для WebAppInfo.

Уведомления о статусе

Миллионы выбирают Telegram за его скорость. Чтобы максимально удовлетворить пользователей, ваш бот также должен быть отзывчивым. Для помощи разработчикам в поддержании своих ботов в рабочем состоянии, @BotFather будет отправлять уведомления о статусе, если увидит, что что-то не так.

Мы проверяем количество ответов и коэффициент конверсии запрос/ответ для популярных ботов (~300 запросов в минуту, это значение может измениться в будущем). Если ваш бот возвращает аномально низкое количество, вы получите уведомление от @BotFather.

Ответ на уведомления

По умолчанию вы получите только одно уведомление на бота в час.

Каждое уведомление имеет следующие кнопки:

Исправлено - Используйте это, если вы нашли проблему с вашим ботом и исправили ее. Если вы нажмете кнопку исправления, мы возобновим отправку уведомлений в обычном режиме, чтобы вы могли увидеть, сработало ли ваше исправление в течение 5-10 минут, а не ждать целый час.
Поддержка - Используйте это, чтобы открыть чат с @BotSupport, если вы не видите никаких проблем с вашим ботом или если вы думаете, что проблема на нашей стороне.
Отключить на 8ч/1нед - Используйте это, если вы не можете исправить своего бота в данный момент. Это отключит все уведомления для данного бота на указанный срок. Мы не рекомендуем использовать эту опцию, так как ваши пользователи могут перейти к более стабильному боту. Вы можете включить уведомления снова в настройках вашего бота через @BotFather.

Отслеживаемые проблемы

В настоящее время мы уведомляем вас о следующих проблемах:

Слишком мало личных сообщений отправляется. Значение: {value} - Ваш бот отправляет гораздо меньше сообщений, чем в предыдущие недели. Это полезно для ботов в стиле новостных рассылок, которые отправляют сообщения без запросов от пользователей. Чем больше значение, тем значительнее разница.
Слишком мало ответов на входящие личные сообщения. Коэффициент конверсии: {value} - Ваш бот не отвечает на все сообщения, которые ему отправляются (коэффициент конверсии запрос/ответ вашего бота был слишком низким хотя бы для двух из последних трех 5-минутных периодов).

Чтобы обеспечить хорошее взаимодействие с пользователем, пожалуйста, отвечайте на все сообщения, которые отправляются вашему боту. Отвечайте на обновления сообщений, вызывая методы send… (например, sendMessage).

Слишком мало ответов на инлайн-запросы. Коэффициент конверсии: {value} - Ваш бот не отвечает на все инлайн-запросы, которые ему отправляются, рассчитывается так же, как и выше. Отвечайте на обновления inline_query, вызывая answerInlineQuery.

Слишком мало ответов на запросы обратного вызова. Коэффициент конверсии: {value}
Слишком мало ответов на запросы обратного вызова игры. Коэффициент конверсии: {value} - Ваш бот не отвечает на все запросы обратного вызова, которые ему отправляются (с играми или без), рассчитывается так же, как и выше. Отвечайте на обновления callback_query, вызывая answerCallbackQuery.

Локальный Bot API

Вы можете размещать и работать с вашей собственной инстанцией нашего открытого Bot API.
Исходный код доступен здесь, вместе с кратким руководством по установке.

После установки сервера не забудьте использовать метод logOut перед перенаправлением запросов на ваш новый локальный URL API.

Ваша локальная инстанция работает по умолчанию на порту 8081 и будет принимать только HTTP-запросы, поэтому необходимо использовать прокси для завершения TLS, чтобы обрабатывать удаленные HTTPS-запросы.

Размещая наш API локально, вы получите доступ к некоторым улучшениям, включая:

API	Максимальный размер загрузки файла	Максимальный размер выгрузки файла	URL WHook	Порт WHook	Максимальное количество соединений WHook
Официальный	20MB	50MB	HTTPS	443,80,88,8443	1-100
Локальный	Неограниченно	2000MB	HTTP	Любой порт	1-100000

Вы можете найти исчерпывающий список здесь.
Все лимиты могут изменяться в будущем, так что следите за @BotNews.

BotFather

Ниже приведено подробное руководство по использованию @BotFather, инструмента Telegram для создания и управления ботами.

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

Используйте команду /newbot, чтобы создать нового бота. @BotFather попросит вас указать имя и имя пользователя, а затем сгенерирует токен аутентификации для вашего нового бота.

Имя вашего бота отображается в контактных данных и в других местах.
Имя пользователя — это короткое имя, используемое в поиске, упоминаниях и ссылках t.me. Имена пользователей имеют длину от 5 до 32 символов и не чувствительны к регистру – но могут содержать только латинские символы, цифры и символы подчеркивания. Имя пользователя вашего бота должно заканчиваться на 'bot', например 'tetris_bot' или 'TetrisBot'.
Токен — это строка, например 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw, которая необходима для авторизации бота и отправки запросов к Bot API. Храните ваш токен в безопасности и надежно, его может использовать любой для управления вашим ботом.

В отличие от имени бота, имя пользователя нельзя изменить позже – поэтому выбирайте его внимательно.
При отправке запроса к api.telegram.org не забудьте добавить слово ‘bot’ перед вашим токеном.

О тексте, описании и медиа профиля

Когда новые пользователи открывают вашего бота, они увидят полезное описание в окне с заголовком «Что может сделать этот бот?».

Правильное установка этого поля в @BotFather позволяет всем сразу получить представление о том, что может сделать ваш бот – ваше описание должно быть кратким, по существу и по теме.

Вы также можете добавить фотографию или видео в это поле с помощью Edit Description Picture в @BotFather.

Дополнительно, как и обычные пользователи, у ботов также есть краткая биография, доступная в их профиле. Если вы не указали это поле при первом создании вашего бота, вы можете установить его в любое время с помощью команды /setabouttext в @BotFather. Пользователи могут взаимодействовать со многими ботами, и у них не будет доступа к их описанию после начала работы с ними – краткое напоминание о назначении бота может быть очень полезным.

Обратите внимание, что как Описание, так и Текст о боте могут быть локализованы на родном языке – каждый пользователь автоматически увидит правильный перевод на своем языке.

У ботов также может быть фотография профиля – вам следует выбрать что-то уникальное и оригинальное, чтобы пользователи могли найти его в своем списке чатов с первого взгляда.

Начиная с 21 апреля 2023 года (Telegram 9.6), вы можете редактировать своего бота непосредственно со страницы его профиля – включая установку пользовательского видео профиля.

Генерация токена аутентификации

Если ваш существующий токен скомпрометирован или вы его потеряли по какой-то причине, используйте команду /token для генерации нового.

Передача прав собственности

Вы можете передать права собственности на вашего бота другому пользователю.
Для этого отправьте /mybots, выберите вашего бота, затем передайте права собственности.
Вы можете передать бота только пользователям, которые взаимодействовали с ним хотя бы раз.

Передача прав собственности даст полное управление ботом другому пользователю – он сможет получить доступ к сообщениям бота и даже удалить его. Передача является постоянной, поэтому, пожалуйста, подумайте об этом внимательно.

Команды BotFather

Оставшиеся команды довольно понятны:

/mybots – возвращает список ваших ботов с удобными инструментами для редактирования их настроек.
/mygames – делает то же самое для ваших игр.

Редактирование ботов

Чтобы отредактировать вашего бота, у вас есть два варианта.

Вы можете использовать доступные команды:

/setname – изменить имя вашего бота.
/setdescription – изменить описание бота (короткий текст до 512 символов). Пользователи увидят этот текст в начале разговора с ботом, заголовок которого 'Что может сделать этот бот?'.
/setabouttext – изменить информацию о боте, более короткий текст до 120 символов. Пользователи увидят этот текст на странице профиля бота. Когда они делятся вашим ботом с кем-то, этот текст отправляется вместе со ссылкой.
/setuserpic – изменить аватар бота.
/setcommands – изменить список команд, поддерживаемых вашим ботом. Пользователи увидят эти команды в виде предложений, когда они вводят / в чате с вашим ботом. См. команды для получения дополнительной информации.
/setdomain – связать домен сайта с вашим ботом. См. раздел виджет входа.
/deletebot – удалить вашего бота и освободить его имя пользователя. Это действие нельзя отменить.

Или вы можете использовать команду /mybots, нажать на вашего бота и использовать современный интерфейс для редактирования.

Начиная с 21 апреля 2023 года (Telegram 9.6), вы можете редактировать общедоступную информацию о вашем боте прямо с его страницы профиля – включая установку пользовательского видео профиля.

Редактирование настроек

/setinline – переключить инлайн-режим для вашего бота.
/setinlinegeo – запросить данные о местоположении для предоставления результатов на основе местоположения в инлайн-режиме.
/setjoingroups – переключить, может ли ваш бот быть добавлен в группы или нет. Все боты должны уметь обрабатывать прямые сообщения, но если ваш бот не предназначен для работы в группах, вы можете отключить эту функцию.
/setinlinefeedback – переключить, должен ли API отправлять обновления о результатах, выбранных пользователями. Подробное объяснение смотрите здесь.
/setprivacy – установить, какие сообщения ваш бот будет получать при добавлении в группу. Смотрите режим конфиденциальности для получения дополнительной информации.

Управление играми

/newgame – создать новую игру.
/listgames – просмотреть список ваших игр.
/editgame – редактировать игру.
/deletegame – удалить существующую игру.

Обратите внимание, что изменения могут вступить в силу через несколько минут.

С этой информацией вы готовы перейти к нашему Полному справочнику API для разработчиков.

Если у вас есть вопросы, ознакомьтесь с нашим FAQ по ботам.
Если у вас возникли проблемы с нашим API, пожалуйста, свяжитесь с @BotSupport в Telegram.