Методи Telegram Bot API та структури даних

У публікації нижче розглянуто деякі типи повідомлень Telegram API та відповідні структури даних із поясненнями.

Загальний огляд

!!!

Объекты данных

Все взаимодействия бота с системой Telegram сопровождаются передачей объектов данных в формате JSON. Существует два типа взаимодействия бота с системой Telegram и три общих типа данных

запрос бота к API одним из предусмотренных методов

бот передает API объект метода

API возвращает объект результата

//

//

//

запрос API к боту с по новому событию

API передает боту объект обновления

бот возвращает объект команды

!!!  это

!!! Webhook

 

//

setWebhook

getWebhookInfo

deleteWebhook

 

Входящие обновления

Каждый вызов бота сервером Telegram содержит json-объект с Обновлением (Update). Существует большое число различных видов обновлений, предназначенных для разного вида содержания, соответственно отличающихся внутренней структурой. Некоторые обновления отражают сообщения, видимые в приватном чате, группе или канале, но есть обновления служебного характера, которые никак не отражаются в пользовательском интерфейсе.

Общим для всех Обновлений является уникальный идентификатор обновления update_id:

update_id Integer Уникальный идентификатор обновления. Идентификаторы обновления начинаются с определенного положительного числа и последовательно увеличиваются. Этот идентификатор становится особенно удобным, если вы используете веб-перехватчики, поскольку он позволяет игнорировать повторяющиеся обновления или восстанавливать правильную последовательность обновлений, если они выходят из строя. Если новых обновлений нет хотя бы неделю, то идентификатор следующего обновления будет выбран случайным образом, а не последовательно.

 

Сообщение (Message)

Семейство обновлений о новых отображаемых в чате, группе, канале объектах выражаются с помощью свойства message, содержащего объект типа Message:

message_id Integer Unique message identifier inside this chat
from User Optional. Sender of the message; empty for messages sent to channels. For backward compatibility, the field contains a fake sender user in non-channel chats, if the message was sent on behalf of a chat.
chat Chat Conversation the message belongs to
date Integer Date the message was sent in Unix time

Текстовое сообщение

 

text String Текст сообщения в кодировке UTF-8
entities Array of MessageEntity Optional. Если текс в Telegram отображается не обычным шрифтом, то это реализуется массивом с разметкой специальных сущностей и стилей (имена !!! пользователей, URL-адреса, команды ботов и т. д.)

Сущность в сообщении /MessageEntity

Объект сущности описывает тип и местоположение фрагмента текста сообщения со специальным смыслом и отображением.

type String Type of the entity. Currently, can be “mention” (@username), “hashtag” (#hashtag), “cashtag” ($USD), “bot_command” (/start@jobs_bot), “url” (https://telegram.org), “email” (do-not-reply@telegram.org), “phone_number” (+1-212-555-0123), “bold” (bold text), “italic” (italic text), “underline” (underlined text), “strikethrough” (strikethrough text), “spoiler” (spoiler message), “code” (monowidth string), “pre” (monowidth block), “text_link” (for clickable text URLs), “text_mention” (for users without usernames), “custom_emoji” (for inline custom emoji stickers)
offset Integer Offset in UTF-16 code units to the start of the entity
length Integer Length of the entity in UTF-16 code units
url String Optional. For “text_link” only, URL that will be opened after user taps on the text
user User Optional. For “text_mention” only, the mentioned user
language String Optional. For “pre” only, the programming language of the entity text
custom_emoji_id String Optional. For “custom_emoji” only, unique identifier of the custom emoji. Use getCustomEmojiStickers to get full information about the sticker

Сущности MessageEntity всегда используются в составе массива в свойстве entities. входящих обновлений, а также исходящих.

//

Контакт (Contact)

Контактные данные пользователя передаются в Сообщении, содержащим свойство contact:  с объектом типа Contact:

phone_number String Contact's phone number
first_name String Contact's first name
last_name String Optional. Contact's last name
user_id Integer Optional. Contact's user identifier in Telegram. This number may have more than 32 significant bits and some programming languages may have difficulty/silent defects in interpreting it. But it has at most 52 significant bits, so a 64-bit integer or double-precision float type are safe for storing this identifier.
vcard String Optional. Additional data about the contact in the form of a vCard

///

Участие в чате message { new_chat_participant, new_chat_member }

//

Автоматический переход в группу /message->migrate_to_chat_id

!!! "migrate_to_chat_id": -1001234567890

Права в группе: my_chat_member

Изменение Участие бота в группе отражается обновлением типа my_chat_member:

Значения status : creator, member, administrator, left. !!! можно получить методом getChatMember, для left возникнет ошибка #400: Bad Request: user not found

При повышении привилегий до администратора свойство new_chat_member будет таким:

//

//

 

XXX

getMe
A simple method for testing your bot's auth token. Requires no parameters. Returns basic information about the bot in form of a User object.

Методы отправки файлов (фото, стикеры, аудио, медиа, документы и др.)

Существует три способа отправки файлов:

  • Используя один из методов отправки указать в качестве источника строку с URL-адресом файла. Telegram автоматически загрузит и разместит файл в сообщении. Максимальный размер 5 МБ для фотографий и максимум 20 МБ для других типов контента.
  • Опубликуйте файл с помощью multipart/form-data обычным способом, которым файлы загружаются через браузер. Максимальный размер 10 МБ для фотографий, 50 МБ для других файлов.
  • Если файл уже когда либо отправлялся в Telegram, то вместо повторной загрузки следует использовать file_id, который Telegram сообщил во время первой загрузки. Поскольку эти файлы уже прошли проверку и уже загружены, ограничений на них нет.

//

  • PDF document image. MIME type: application/pdf
  • Mp3 audio. MIME type: audio/mpeg
  • Mov Quicktime video. MIME type: video/quicktime
  • Mp4 MPEG-4 video. MIME type: video/mp4

Метод отправки фото /sendPhoto

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

  • JPEG image. MIME type: image/jpeg
  • GIF image. MIME type: image/gif
  • PNG image. MIME type: image/png
  • WEBP image. MIME type: image/webp
chat_id Integer or String Unique identifier for the target chat or username of the target channel (in the format @channelusername)
message_thread_id Integer Optional. Уникальный идентификатор целевой ветки сообщений (темы) форума; только для супергрупп форума
photo InputFile,
String
Фото для отправки. Передайте file_id в виде строки, чтобы отправить фотографию, которая существует на серверах Telegram (рекомендуется), передайте URL-адрес HTTP в виде строки, чтобы Telegram мог получить фотографию из Интернета, или загрузите новую фотографию, используя multipart/form-data. Фотография должна быть размером не более 10 МБ. Суммарная ширина и высота фотографии не должны превышать 10000. Соотношение ширины и высоты должно быть не более 20. Подробнее об отправке файлов »

  • String <file_id> идентификатор картинки, уже загруженной в систему Telegram
  • String <url> произвольная ссылка на файл для загрузки в систему, URL необходимо подготовить для отправки , файл не загружается повторно, если уже загружался раньше
  • InputFile ? можно получить как  new CURLFile, который при использовании параметра CURLOPT_POSTFIELDS выполняет загрузку файла НО ЭТО НЕ ТОЧНО!
  • InputFile !!! эксперименты с file_get_contents() результаты пока не дали
caption String Optional..Photo caption (may also be used when resending photos by file_id), 0-1024 characters after entities parsing
parse_mode String Optional..Mode for parsing entities in the photo caption. See formatting options for more details.
caption_entities Array of
MessageEntity
Optional..A JSON-serialized list of special entities that appear in the caption, which can be specified instead of parse_mode
has_spoiler Boolean Optional..Pass True if the photo needs to be covered with a spoiler animation
disable_notification Boolean Optional..Sends the message silently. Users will receive a notification with no sound.
protect_content Boolean Optional..Protects the contents of the sent message from forwarding and saving
reply_to_message_id Integer Optional..If the message is a reply, ID of the original message
allow_sending_without_reply Boolean Optional..Pass True if the message should be sent even if the specified replied-to message is not found
reply_markup InlineKeyboardMarkup
ReplyKeyboardMarkup
ReplyKeyboardRemove
ForceReply
Optional..Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user.

!!! Фото для отправки можно задать через file_id в виде строки, если фотография существует на серверах Telegram (рекомендуется), передайте URL-адрес HTTP в виде строки, чтобы Telegram мог получить фотографию из Интернета, или загрузите новую фотографию, используя multipart/form-data. Фотография должна быть размером не более 10 МБ. Суммарная ширина и высота фотографии не должны превышать 10000. Соотношение ширины и высоты должно быть не более 20.

Результат успешно отправки JSON объект:

При повторной отправке дубликата указанием URL фото Telegram определить дублирование и file_unique_id сохранится тем же, но file_id изменяется при каждой отправке. Вероятно, дублирование фото Telegram определяет по URL без повторной загрузки самого файла, поэтому если файл изменится в источнике по URL, Telegram продолжит отображать его в первоначальном виде.

Документация Telegram API рекомендует использовать file_id в целях экономии ресурсов системы.

//

sendSticker
Use this method to send .webp stickers. On success, the sent Message is returned.

sendContact
Use this method to send phone contacts. On success, the sent Message is returned.

getUserProfilePhotos

Use this method to get a list of profile pictures for a user. Returns a UserProfilePhotos object.

 

sendMessage
Use this method to send text messages. On success, the sent Message is returned.

editMessageText
Use this method to edit text and game messages. On success, if the edited message is not an inline message, the edited Message is returned, otherwise True is returned. Метод применим к сообщению без reply_markup  или с inline_keyboard, иначе вызывает ошибку #400 Bad Request: message can't be edited!

deleteMessage
Use this method to delete a message, including service messages, with the following limitations:
- A message can only be deleted if it was sent less than 48 hours ago.
- Service messages about a supergroup, channel, or forum topic creation can't be deleted.
- A dice message in a private chat can only be deleted if it was sent more than 24 hours ago.
- Bots can delete outgoing messages in private chats, groups, and supergroups.
- Bots can delete incoming messages in private chats.
- Bots granted can_post_messages permissions can delete outgoing messages in channels.
- If the bot is an administrator of a group, it can delete any message there.
- If the bot has can_delete_messages permission in a supergroup or a channel, it can delete any message there.
Returns True on success.

Метод уведомления на обратный вызов /answerCallbackQuery

метод для отправки ответов на запросы CallbackQuery, отправленные со встроенной клавиатуры. Ответ отображается в виде уведомления в верхней части экрана чата или в виде предупреждения. В случае успеха возвращается True.
!!!

Повідомлення update

//

"message"

"edited_message": {

getUpdates

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

Не может выполняться при установленном webhook, и тем более во время вызова webhook, в этих случаях возникнет ошибка #409 Conflict: can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first!

Сообщение /message

Подпись с оформлением caption, caption_entities

caption

Свойство caption_entities содержит массив объектов типа MessageEntity, которые описывают особые сущности в подписи:
mention (@username)
hashtag (#hashtag)
cashtag ($USD)
bot_command (/start@jobs_bot)
url (https://telegram.org)
email (do-not-reply@telegram.org)
phone_number (+1-212-555-0123)
bold (bold text)
italic (italic text)
underline (underlined text)
strikethrough (strikethrough text)
spoiler (spoiler message)
code (monowidth string)
pre (monowidth block)
text_link (for clickable text URLs)
text_mention (for users without usernames)
custom_emoji (for inline custom emoji stickers)

 

Разметка ответов /reply_markup

!!!

Разметка ответов является необязательным свойством отправляемого ботом сообщения, но это свойство отсутствует в результирующем объекте метода sendMessage.

Кнопки ответа reply_markup

Для отображения кнопок ответа в сообщение добавляется массив reply_markup с описанием разметки:

 

Клавиатура keyboard

Для відображення кнопок під повідомленням бота до повідомлення додається об'єкт reply_markup.

//

keyboard - разметка может содержать любое число массивов строк, но отображены будут только первые 9 непустых массива; пустые массивы игнорируются; массив строки может содержать любое число элементов, но отображены будут только первые 12.

is_persistent Boolean Optional. Requests clients to always show the keyboard when the regular keyboard is hidden. Defaults to false, in which case the custom keyboard can be hidden and opened with a keyboard icon.

one_time_keyboard (Boolean) необязательный, по умолчанию false постоянно отображает кнопки ответа, при true кнопки будут скрыты после первого использования, но останутся доступными.

resize_keyboard (Boolean) необязательный, по умолчанию false кнопки займут место клавиатуры, используя всю высоту, при true кнопки освободят избыточное место, но если кнопки потребуют больше места, то появится возможность их прокрутки, независимо от значения параметра.

input_field_placeholder (String) необязательный, ?

selective (Boolean) необязательный, по умолчанию false показывает клавиатуру всем пользовтаелям, при true только определенным пользователям:
1) пользователи, @упомянутые в тексте объекта «Сообщение»
2) если сообщение бота является ответом (имеет response_to_message_id), отправитель исходного сообщения.

//

Удаление клавиатуры ответов ReplyKeyboardRemove

Объект ReplyKeyboardRemove в составе сообщения удаляет текущую клавиатуру ответов.

Встроенные кнопки inline_keyboard

Для відображення кнопок під повідомленням бота до повідомлення додається об'єкт reply_markup, который содержит !!!.

Каждое нажатие кнопки будет вызывать сообщение update с объектом callback_query структуры:

 

Отложенное сообщение

!!! по непроверенной гипотезе отправка сообщения отложенного до запланированного момента времени реализуется параметром schedule_date в том же формате, что и "date": !!!

Методы

Отправить фото sendPhoto

описание перенесено !!!

Повідомити про дію sendChatAction

Використовуйте цей метод, коли вам потрібно повідомити користувача, що щось відбувається на боті. Статус встановлюється в додатку на 5 секунд або менше (в браузері не відображається). В Повертає True у разі успіху

  • метод: 'sendChatAction'
  • объект параметров:
    • 'chat_id': Integer|String
    • 'action': String
      • 'typing' for text messages,
      • 'upload_photo' for photos,
      • 'record_video' | 'upload_video' for videos,
      • 'record_voice' | 'upload_voice' for voice notes,
      • 'upload_document' for general files,
      • 'choose_sticker' for stickers,
      • 'find_location' for location data,
      • 'record_video_note' | 'upload_video_note'

Обработка inline-запросов

Реализация ботом inline-запросов позволит пользователю взаимодействовать с ботом не в чате бота, а прямо в строке сообщения, которое начинается с идентификатора бота.

Для обработки ботом inline-запросов, во-первых, эта опция бота должна быть включена в BotFather командой /setinline.

Команды

//

setMyCommands

Use this method to change the list of the bot's commands. See this manual for more details about bot commands. Returns True on success.

commands Array of BotCommand Yes A JSON-serialized list of bot commands to be set as the list of the bot's commands. At most 100 commands can be specified.
scope BotCommandScope Optional A JSON-serialized object, describing scope of users for which the commands are relevant. Defaults to BotCommandScopeDefault.
language_code String Optional A two-letter ISO 639-1 language code. If empty, commands will be applied to all users from the given scope, for whose language there are no dedicated commands

deleteMyCommands

Use this method to delete the list of the bot's commands for the given scope and user language. After deletion, higher level commands will be shown to affected users. Returns True on success.

scope BotCommandScope Optional A JSON-serialized object, describing scope of users for which the commands are relevant. Defaults to BotCommandScopeDefault.
language_code String Optional A two-letter ISO 639-1 language code. If empty, commands will be applied to all users from the given scope, for whose language there are no dedicated commands

getMyCommands

Use this method to get the current list of the bot's commands for the given scope and user language. Returns an Array of BotCommand objects. If commands aren't set, an empty list is returned.

Parameter Type Required Description
scope BotCommandScope Optional A JSON-serialized object, describing scope of users. Defaults to BotCommandScopeDefault.
language_code String Optional A two-letter ISO 639-1 language code or an empty string

 

Кнопка меню чата

//

getMyCommands

Use this method to get the current list of the bot's commands for the given scope and user language. Returns an Array of BotCommand objects. If commands aren't set, an empty list is returned.
scope BotCommandScope Optional A JSON-serialized object, describing scope of users. Defaults to BotCommandScopeDefault.
language_code String Optional A two-letter ISO 639-1 language code or an empty string

setChatMenuButton

Use this method to change the bot's menu button in a private chat, or the default menu button. Returns True on success.
chat_id Integer Optional Unique identifier for the target private chat. If not specified, default bot's menu button will be changed
menu_button MenuButton Optional A JSON-serialized object for the bot's new menu button. Defaults to MenuButtonDefault

getChatMenuButton

//

Chat

//

getChat

Метод getChat позволяет получить актуальную информацию о чате (текущее имя пользователя для разговоров один на один, текущее имя пользователя, группы или канала и т. д.).

chat_id Integer or String Уникальный идентификатор целевого чата или имя пользователя целевой супергруппы или канала (в формате @channelusername)

Возвращает объект чата в случае успеха:

  • small_file_id, big_file_id вопреки ожиданиям метод sendPhoto эти идентификаторы не принял и сообщил об ошибке парсинга пути
getChatMemberCount

Метод getChatMemberCount позволяет получить количество участников в чате. Параметры аналогичны методу getChat Возвращает Int в случае успеха.

 

getChatMember

Метод getChatMember  получает информацию об участнике чата. Способ гарантированно сработает для пользователей, только если бот является администратором в чате. Параметры метода:

chat_id Integer or String Уникальный идентификатор целевого чата или имя пользователя целевой супергруппы или канала (в формате @channelusername)
user_id Integer Уникальный идентификатор целевого пользователя

Возвращает объект ChatMember в случае успеха:

setChatPermissions

kickChatMember
Используйте этот метод, чтобы исключить пользователя из группы или супергруппы. В случае с супергруппами пользователь не сможет вернуться в группу самостоятельно по инвайт-ссылкам и т.д., если предварительно не разбанится. Чтобы это работало, бот должен быть администратором в группе. Возвращает True в случае успеха.
Use this method to kick a user from a group or a supergroup. In the case of supergroups, the user will not be able to return to the group on their own using invite links, etc., unless unbanned first. The bot must be an administrator in the group for this to work. Returns True on success.

unbanChatMember
Используйте этот метод, чтобы разблокировать ранее исключенного пользователя в супергруппе. Пользователь не вернется в группу автоматически, но сможет присоединиться по ссылке и т. д. Чтобы это работало, бот должен быть администратором в группе. Возвращает True в случае успеха.
Use this method to unban a previously kicked user in a supergroup. The user will not return to the group automatically, but will be able to join via link, etc. The bot must be an administrator in the group for this to work. Returns True on success.

 

Heap

editMessageMedia

sendMediaGroup

editMessageReplyMarkup применимо только к определению InlineKeyboard

createNewStickerSet

uploadStickerFile
Используйте этот метод, чтобы загрузить файл .PNG со стикером для последующего использования в методах createNewStickerSet и addStickerToSet (можно использовать несколько раз). Возвращает загруженный файл в случае успеха.

getChat

 

Источники

  •  Пример связи 1С и мессенджера Telegram. Получение данных из 1С запросом из Telegram //infostart.ru
  • Телеграм бот. Отчеты на мобильном устройстве без изменения конфигурации (Telegram bot) //infostart.ru

Leave a Reply