Боты Telegram

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

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

Для работы с Bot API разработана .NET библиотека.

Взаимодействовие пользователей с ботом

Через чат или группу

inline mode - получение контента от бота через строку запроса

приватный чат:

или публичный чат (группа):

Взаимодействие сервера бота с сервером Telegram

У каждого бота есть уникальный идентификатор <token>, который указывается в запросах к серверу Telegram.

Как бот получает обновления

Входящие сообщения хранятся на сервере пока бот не получит их, но не дольше 24 часов.

1. long pooling

2. Webhooks

• Обновления приходят на указанный url HTTPS POST запросом. Желательно использовать url вида www.example.com/your_token, токен которого сообить только Telegram.
• Необходимо использовать ssl сертификат (если сертификат самоподписнный, нужно его загрузить)
• Поддерживаемые порты 443, 80, 88, 8443
• Wildcart сертификаты могут не работать, CN должен совпадать с доменом
• Не поддерживается переадресация

Ответный запрос можно отправить ответ следующими способами:

Когда используется Webhooks, нельзя получать обновления через long pooling.

Объект Update

Часть объекта Update

Содержит поля Ответ

Message

Сообщение в чате

• message_id

• from (User)

• date

• chat (Chat)

• text

• [MessageEntity(особые сущности в текстовом сообщении):хештеги, имена пользователей, bot command, url, email, ...]

• audio

• video

• photo

• Document(файл, не являющийся фото, voice message и audio):file_id, thumb, file_name, mime_type, file_size

• Contact: phone_number, ...

• new_chat_member

• ...

InlineQuery

входящий inline запрос

• id

• from (User)

• query

• Location

• offset

для ответа используется метод answerInlineQuery с параметрами:

• [InlineQueryResult(50max):audio,..., video, gif, article, title, url,

  InputMessageContent

  (сообщение которое будет отправлено в чат),

  InlineKeyboardMarkup

  , ...]

• cache_time

• is_personal(кешируется только для одно пользователя)

• next_offset(for pagitaions)

• switch_pm_text+switch_pm_parameter(для переключения пользователя в pm)

ChosenInlineResult

один из InlineQueryResult выбранных пользователем

• result_id (id выбранного результата)
• from (User)
• location
• inlnie_message_id(присутствует, если нажата кнопка клавиатуры под сообщением)
• query

CallbackQuery

входящий запрос от callback button из inline keyboard

• id (uid запроса)
• from (User)
• Message (присутствует, если нажата кнопка под сообщением, отправленным ботом)
• inline_message_id (присутствует, если кнопка под сообщением, отправленным через inline mode)
• data

answerCallbackQuery (ответ может быть отправлен на запрос от inline keyboard, и отобразит всплывающую подсказку пользователю):

• callback_query_id (uid запроса, на который будет ответ)
• +text (text of the notifacation)
• +show_alert (alert insteaf of notification)

Объекты сообщений для работы с пользовательскими клавиатурами

Поля этих типов присутствуют в методах send...

ReplyKeyboardMarkup

Отобразить пользовательскую клавиатуру

• [KeyboardButton]
• resize_keyboard (выровнять клавиатуру по вертикали, иначе будет размером стандартной клавиатуры)
• one_time_keyboard (спрятать клавиатуру сразу после использования и показать стандартную, пользователь сможет открыть эту клавиатуру опять по спец.кнопке)
• selective (показать клавиатуру только определенным пользователям)

ReplyKeyboardHide

Спрятать пользовательскую клавиатуру и отобразить стандартную

• hide_keyboard
• selective (спрятать клавиатуру только для определенных пользователей, например, при голосовании прятать у того, кто проголосовал, но продолжать показывать тем, кто еще не проголосовал)

InlineKeyboardMarkup

Отобразить встроенную клавиатуру под сообщением

• [InlineKeyboardButton]

KeyboardButton

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

• text (если доп.поля не используется, текст будет отправлен боту как сообщение)
• request_contact (будет отправлен номер телефона пользователя при нажатии)
• request_location (будет отправлено текущее местоположение пользователя при нажатии)

InlineKeyboardButton

Обязательно использовать одно из доп.полей

• text
• +url
• +callback_data (данные будут отправлены боту в callback на эту кнопку)
• +switch_inline_query (

  просит пользователя выбрать чат, открывает его и вставляет имя бота в строку ввода, можно также указать запрос, и в этом случае пользователь сразу может увидеть inline результаты

  )

ForceReply

Пользователю откроется интерфейс ответа на сообщение, как если бы он сам нажал "ответить на сообщение"

• force_reply
• selective

Методы

getMe

Тестовый запрос

sendMessage

• chat_id
• text
• repyl_makrup (

  ImlineKeyboardMarkup

  ,

  ReplyKeyboardMarkup

  ,

  ReplayKeyboardHide

  or

  ForceReply

  - объекты для работы со встроенными и пользовательскими клавиатурами)
• ...

send...

Отправка аудио, видео и т.п.

• repyl_makrup (

  ImlineKeyboardMarkup

  ,

  ReplyKeyboardMarkup

  ,

  ReplayKeyboardHide

  or

  ForceReply

  - объекты для работы со встроенными и пользовательскими клавиатурами)
• ...

sendChatAction

Показать всплывающее сообщение на 5 секунд или меньше

• chat_id
• action

getUserProfilePhotos

• user_id
• offset
• limit

getFile

• file_id

editMessageText

• chat_id
• message_id
• inline_message_id
• text
• parse_mode
• disable_web_page_preview

editMessageCaption

• chat_id
• message_id
• inline_message_id
• caption
• replay_markup (

  InlineKeyboardMarkup

  )

editMessageReplyMarkup

• chat_id
• message_id
• inline_message_id
• r

  eplay_markup (

  InlineKeyboardMarkup

  )

Inline mode

1. Пользователь пишет в строке @botName /query
2. Бот возвращает результаты (возможны все виды контента, стикеры, местополложения, документы и т.д.)
3. Пользователь нажимает на одном из результатов
4. Выбранный результат отправляется в текущий чат

Переключение между inline и приватным режимами

При нажатии на "Sign in to ToyTube" (это называется "Switch to PM" кнопкой) произойдет переключение в приватный режим, где можно ввести приваные данные, например, авторизоваться. а далее переключится обратно.

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

Когда пользователь отправляет в чат контент через бота, то в шапке сообщения указывается кто и через какого бота отправил это сообщение, например, Pavel Durov @gif (каптинка). @gif - это ссылка, при нажатии название бота вставляется в строку ввода - вирусное распространение.

Пользовательские клавиатуры

1. Пользователь отправляет сообщение
2. Ответом бота является то, что нужно показать пользовательскую клавиатуру (ReplyKeyboardMarkup). На кнопках клавиатуры может быть текст и emoji
3. Пользователь нажимает кнопку на клавиатуре
4. Боту отправляется команда, соответствующая нажатой на клавиатуре кнопке

Inline клавиатуры

Это клавиатуры, которые отображаются под сообщением. При нажатии на кнопки такой клавиатур сообщение в чат не отправляется, такие кноки действуют как:

• callback button

  - сообщение в чат не отправляется, но бот получает команду и может ответить всплывающим alert, или может отредактировать свои сообщения.

• url button

  - открывает ссылку в браузере.

• switch to inline button

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

Команды

/command [optional] [argument]

Команда всегда начинается с / и не может быть длинней 32 символов, содержит латинские символы, числа и _.

1. Пользователь набирает /
2. Telegram предлагает пользователю список команд (указывается в нстройках) бота
3. Пользователь нажимает на команду
4. Команда отправляется боту

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

Если в чате несколько ботов, для исключения путаницы нужно добавлять имя бота после команды /start@BotName

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

Каждый бот должен содержать обязательные команды:

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

Форматирование

Текст в сообщениях бота может форматироваться следующим образом:

• bold
• italic
• fixed-width text
• inline link

Приватный режим

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

• команды /
• ответы на сообщения самого бота
• сервисные сообщения (пользователя добавили или удалили из группы и т.п.)

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

Внешнее связывание

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

Каждый бот имеет ссылку, которая открывают чат с ботом в Telegram

https://telegram.me/<bot username>

Можно добавить параметры в эту ссылку:

• start - открывает 1-1 чат с ботом
• startgroup - пользователю предлагается выбрать группу, в которую добавить данного бота.

Бот получит /start PAYLOAD, где PAYLOAD - значение параметра.

Местоположение и Номер телефона

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

‏Source vsrwd.ru