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

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

Зміст

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

!!!

Специальные объекты

BotFather #93372553

Объект типа User

Telegram #777000

Объект типа User осуществляет рассылку сообщений от имени системы Telegram. Формально не считается ботом.

Group @GroupAnonymousBot #1087968824

Объект типа User осуществляет отправку сообщений при автоматической миграции бота из чата group в supergroup.

 

Типы и структуры объектов данных

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

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

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

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

Если запрос не был успешным, код будет соответствовать ошибке клиента 400..499 и будет установлено описание ошибки.

Примеры ошибок:

  • 400: Bad Request: chat not found возникает если
    • чат не существует или недоступен
      • в том числе, если это чат другого бота
    • бот не является участником группы чата
  • 403: Forbidden: bot can't initiate conversation with a user  возникает при попытке отправить сообщение в чат пользователя, который не подключался к боту и не вызывал команду /start
  • 403: Forbidden: bot is not a member of the channel chat  при попытке отправить сообщение в чат канала, в который бот не подписан

 

//

запрос 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

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

Обычное текстовое сообщение содержит в обновлении свойство message типа Message дополнительно со свойствами:

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

неподтвержденный список языков:

  • IDL
  • Java
  • Javascript,
  • C#
  • C
  • C++
  • D
  • PHP
  • Objective-C
  • Python
  • Fortran
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. входящих обновлений, а также исходящих.

//

Ответное сообщение

Сообщение данное в ответ на другое сообщение имеет дополнительное свойство reply_to_message типа Message с его полным содержанием:

 

Контакт (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

///

Обновление о новом подписчике в чате /new_chat_participant, new_chat_member

//

Обновление об изменении имени группы /new_chat_title

При изменение имени группы бот получит обновление с сообщением:

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

!!! "migrate_to_chat_id": -1001234567890

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

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

Значения "type": "group", "supergroup", "channel"

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

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

//

//

Обновление о публикации в канале

//

Обновление о подписке бота в группу комментариев канала

//

Обновление о подписке нового пользователя в чат

Обновление о комментарии к публикации в канале

Обновление о переходе чата в режим форума /group_chat_created

Переход group в режим форума приводит к автоматической миграции в новую supergroup, но обновление о переходе приходит до миграции

Обновление о миграции чата /migrate_to_chat_id, migrate_from_chat_id

При переходе чата из типа group в supergroup происходит через миграцию, о которой сообщает обновление из исходного чата:

Затем из нового чата поступает обновление migrate_from_chat_id, со свойством sender_chat

Двум описанным обновлениям предшествует обновление my_chat_member.

Обновление о создании темы в форуме /forum_topic_created

//

Обновление о сообщении и ответе в теме форума

//

Обновление об ответе на сообщение в теме форума

 

//

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.

Отправка сообщений

Метод отправки текстового сообщения /sendMessage

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

chat_id Integer,
String
Уникальный идентификатор целевого чата или имя пользователя целевого канала (в формате @channelusername)
message_thread_id Integer Optional. Уникальный идентификатор целевой ветки сообщений (темы) форума; только для супергрупп форума
text String Текст отправляемого сообщения, 1-4096 отображаемых символов после без символов определяющих сущности
parse_mode String Optional. Режим разбора сущностей в тексте сообщения:
  • по умолчанию (null) сущности задаются массивом объектов в параметре entities
  • 'HTML' сущности определяются xml-тегами
  • 'Markdown ' и 'MarkdownV2 ' сущности задаются маркерами

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

entities Array
of MessageEntity
Optional. JSON-сериализация массива объектов специальных сущностей, размеченных тексте сообщения:

disable_web_page_preview Boolean Optional. Отключает предварительный просмотр ссылок в этом сообщении
disable_notification Boolean Optional. Отправляет беззвучное сообщение (без звукового уведомления получателя)
protect_content Boolean Optional. Защищает содержимое отправленного сообщения от пересылки и сохранения
reply_to_message_id Integer Optional. При указании ID первичного сообщения из этого же чата,  метод отправит сообщение-ответ на него
allow_sending_without_reply Boolean Optional. True позволяет отправить сообщение-ответ, даже если первичное сообщение с ответом не найдено
reply_markup InlineKeyboardMarkup
ReplyKeyboardMarkup
ReplyKeyboardRemove
ForceReply
Optional. Json-сериализазция объекта управляющего разметкой клавиатур

Меню набора ответов ReplyKeyboardMarkup

Меню ответов будет сформировано если объект типа ReplyKeyboardMarkup будет добавлен в сообщение...

Кнопка набора ответов KeyboardButton

Кнопка в составе массива keyboard типа ReplyKeyboardMarkup обычно задает некоторый предопределенный текст, заданный обязательным свойством объекта кнопки:

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

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

request_user KeyboardButtonRequestUser Optional. Если указано, нажатие кнопки откроет список подходящих пользователей. Нажатие на любого пользователя отправит его идентификатор боту в служебном сообщении «user_shared».
request_chat KeyboardButtonRequestChat Optional. нажатие кнопки откроет список подходящих чатов. При нажатии на чат боту будет отправлен его идентификатор в служебном сообщении «chat_shared».
request_contact Boolean Optional. Если установлено значение True, номер телефона пользователя будет отправлен в качестве контакта при нажатии кнопки.
request_location Boolean Optional. Если True, текущее местоположение пользователя будет отправлено при нажатии кнопки.
request_poll KeyboardButtonPollType Optional. Если указано, пользователю будет предложено создать опрос и отправить его боту при нажатии кнопки.
web_app WebAppInfo Optional. Если указано, описанное веб-приложение будет запускаться при нажатии кнопки. Веб-приложение сможет отправлять служебное сообщение «web_app_data».

 

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

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

  • Используя один из методов отправки указать в качестве источника строку с 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..Режим разбора сущностей в подписи к фото (дівись sendMessage)
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 объект:

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

  • Миниатюра #0, кадрированное по меньшему размеру и масштабировано до 90 x 90 px
  • фото #1, не больше 320 px по ширине или высоте
  • фото #2, не больше 800 px по ширине или высоте
  • фото #3, не больше 1280 px по ширине или высоте
  • ...
  • Последний индекс соответствует оригиналу

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

Документация Telegram API рекомендует при повторной отправке изображения использовать в свойстве photo  дескриптор file_id, полученный при первой успешной отправке. Это позволяет боту минимизировать использование ресурсов серверов Telegram.

При любом способе отправки дубликата фото file_unique_id для каждого размера останется прежним, а 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.

Метод получения ссылки на файл для загрузки /getFile

Метод необходимо использовать перед загрузкой файла доступного боту, он возвращает размер файла и фрагмент URL для загрузки. Метод использует единственный параметр идентификатора файла, который передает API при использовании:

  • методов  sendMessage, sendPhoto, sendVideo, sendAnimation, sendAudio, sendDocument
  • обновлений сообщений с картинками и другими файлами
  • методов getUserProfilePhotos, getChat
file_id String Идентификатор файла ранее полученный ботом через API

Результатом успешного вызова метода getFile является объект:

API не гарантирует сохранение исходного имени файла и mime-типа, но гарантируется доступность файла для загрузки не менее 1 часа по URL:

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

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

callback_query_id String Unique identifier for the query to be answered
text String
..200 chars
Optional.Текст уведомления. Если не указано, пользователю ничего не будет показано, 0-200 символов
show_alert Boolean Optional. Если True, клиент отобразит оповещение вместо уведомления в верхней части экрана чата. Значение по умолчанию – ложь
url String Optional. URL-адрес, который будет открыт клиентом пользователя. Если вы создали игру и приняли условия через @BotFather, укажите URL-адрес, который открывает вашу игру. Обратите внимание, что это будет работать, только если запрос исходит от кнопки callback_game. В противном случае вы можете использовать такие ссылки, как t.me/your_bot?start=XXXX, которые открывают вашего бота с параметром.
cache_time Integer Optional. Максимальное время в секундах, в течение которого результат запроса обратного вызова может кэшироваться на стороне клиента. Приложения Telegram будут поддерживать кэширование, начиная с версии 3.14. По умолчанию 0.

Метод установки набора команд /setMyCommands

Метод setMyCommands устанавливает новый набор команд доступных пользователю или пользователям в меню чата, старый набор при этом удаляется. Дополнительно метод позволяет установить область доступности команд набора scope из семи возможных, и установить язык набора.
Параметры метода:

commands Array of BotCommand JSON сериализация списка команд бота, который будет установлен как список команд бота (не более 100 команд)
scope BotCommandScope Optional. Сериализованный объект JSON, описывающий область, в которой команды будут доступны; по умолчанию используется BotCommandScopeDefault
language_code String Optional. Двухбуквенный код языка ISO 639-1. Если пусто, команды будут применяться ко всем пользователям из заданной области, для языка которых нет выделенных команд

Набор команд в параметре commands представляется индексированным массивом объектов типа BotCommand с описанной структурой:

command String Текст команды; 1-32 символа. Может содержать только строчные английские буквы, цифры и символы подчеркивания
description String Описание команды; 1-256 символов
language_code String Optional. Двухбуквенный код языка ISO 639-1. Если пусто, команды будут применяться ко всем пользователям из заданной области, для языка которых нет выделенных команд

Область доступности команд в параметре scope  представляется объектом типа BotCommandScope, в котором возможны четыре уровня отбора: тип чата, тип подписчика,  определенный чат, определенный подписчик. Объект имеет структуру:

type String один из идентификаторов области доступности:
  • default
  • all_private_chats
  • all_group_chats
  • all_chat_administrators
  • chat
  • chat_administrators
  • chat_member
chat_id Integer or String Optional для области типа chat, chat_administrators или chat_member.
id целевого чата или username целевой супергруппы (в формате @supergroupusername)
user_id Integer Optional для области типа chat_member.
Уникальный идентификатор id целевого пользователя

Пример установки двух команд в чате @matrix избранному пользователю:

Метод удаления набора команд /deleteMyCommands

Метод deleteMyCommands удаляет набор команд доступный пользователю или пользователям в меню чата. Действие метода противоположно  setMyCommands, поэтому он идентичен в параметрах scope   и language_code параметра commands .

 

Подробнее о командах бота см. в этом руководстве. Возвращает 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 имеют тип ChatPhoto, поэтому вопреки ожиданиям метод sendPhoto их не принимает и сообщает об ошибке 400: Bad Request: can't use file of type ChatPhoto as Photo.

В случае успеха метода getChat http-запрос получает код ответа 200. Если запрос не был успешным, код будет соответствовать ошибке клиента 400..499 и будет установлено описание ошибки. Например:

  • 400: Bad Request: chat not found /если чат не существует или бот не является подписчиком чата группы
  • 403: Forbidden: bot is not a member of the channel chat

 

//

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.

 

Ошибки

Успешно обработанный запрос к Bot API возвращает код #200 и content с json-сериализацией объекта, в котором обязательно присутствует свойство ok в значении true. Очевидно, не все запросы к Bot API завершаются успешным выполнением по разным причинам.

Ограничения

Ошибка #429 /Too Many Requests

Telegram Bot API устанавливает ограничение на интенсивность новый сообщений, их число не должно превышать 20 в минуту в отдельном чате. Если это ограничение нарушается, запрос завершается кодом #429 "Too Many Requests: retry after 40". В сообщении "40" означает число секунд, в течении которого лимит будет действовать. Упорные попытки отправить сообщение будут снова приводить к коду #429, но счетчик секунд будет уменьшаться. Значение требуемого таймаута содержится в content ответа API:

 

Heap

editMessageMedia

sendMediaGroup

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

createNewStickerSet

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

getChat

 

Источники

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

Leave a Reply