У публікації нижче розглянуто деякі типи повідомлень Telegram API та відповідні структури даних із поясненнями.
Bots: An introduction for developers //core.telegram.org/bots
- Telegram Bot API is an HTTP-based interface created for developers keen //core.telegram.org/bots/api
Справочник по Bot API //tlgrm.ruTelegram Bot SDK //github.com
Лимиты Telegram //limits.tginfo.me
Всё, о чём должен знать разработчик Телеграм-ботов tmat@habr.com (24 Feb 2021)Пишем ботов для Telegram на языке Python //mastergroosha.github.io
Загальний огляд
!!!
Специальные объекты
BotFather #93372553
Объект типа User
|
1 2 3 4 5 |
"from": { "id": 93372553, "is_bot": true, "first_name": "BotFather", "username": "BotFather" } |
Telegram #777000
Объект типа User осуществляет рассылку сообщений от имени системы Telegram. Формально не считается ботом.
|
1 2 3 4 |
"from": { "id": 777000, "is_bot": false, "first_name": "Telegram" } |
Group @GroupAnonymousBot #1087968824
Объект типа User осуществляет отправку сообщений при автоматической миграции бота из чата group в supergroup.
|
1 2 3 4 5 |
"from": { "id": 1087968824, "is_bot": true, "first_name": "Group", "username": "GroupAnonymousBot" } |
Типы и структуры объектов данных
Все взаимодействия бота с системой Telegram сопровождаются передачей объектов данных в формате JSON. Существует два типа взаимодействия бота с системой Telegram и три общих типа данных
запрос бота к API одним из предусмотренных методов
бот передает API объект метода
|
1 2 3 4 5 |
{ "method": "sendMessage", "chat_id": 123456789, "text": "Sending a text message to a char" } |
API возвращает объект результата
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
{ "ok": true, "result": { "message_id": 456, "from": { "id": 1234567890, "is_bot": true, "first_name": "ReKS", "username": "ReKSbizBot" }, "chat": { "id": -1001234567890, "title": "Demo Supergroup", "type": "supergroup" }, "date": 1675326463, "text": "Bot may sendMessage", "entities": [{...},...], "reply_markup": {...} } } |
Если запрос не был успешным, код будет соответствовать ошибке клиента 400..499 и будет установлено описание ошибки.
|
1 2 3 4 5 |
{ "ok": false, "description": "Bad Request: chat_id is empty" } } |
Примеры ошибок:
- 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 передает боту объект обновления
|
1 2 3 4 5 6 |
{ "update_id":172287334, "...":{ ... } } |
бот возвращает объект команды
!!! это
!!! 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
неподтвержденный список языков:
|
| 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 с его полным содержанием:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
{ "update_id": 460398861, "message": { ... "reply_to_message": { "message_id": 1234, "from": { "id": 3456789, "is_bot": true, "first_name": "Reks", "username": "ReKSbizBot" }, "chat": { "id": 3456789, "first_name": "Peks", "username": "PeKS", "type": "private" }, "date": 1675236677, "text": "Please, reply me", "entities": [...] }, "text": "Do you ask me to reply?" } } |
Контакт (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
//
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
{ "update_id":172287320, "message":{ "message_id":7, "from":{ "id":1234567890, "is_bot":false, ... "language_code":"uk"}, "chat":{ "id":-234567890, "title":"Demo group", "type":"group", "all_members_are_administrators":true }, "date":1674133413, "new_chat_participant":{ "id":3456789, ...}, "new_chat_member":{...}, "new_chat_members":[{...}] } } |
Обновление об изменении имени группы /new_chat_title
При изменение имени группы бот получит обновление с сообщением:
|
1 2 3 4 5 6 7 8 9 10 |
{ "update_id": 172289542, "message": { "message_id": 777, "from": {...}, "chat": {...}, "date": 1675364635, "new_chat_title": "My new chat title" } } |
Автоматический переход в группу /message->migrate_to_chat_id
!!! "migrate_to_chat_id": -1001234567890
Права в группе: my_chat_member
Изменение Участие бота в группе отражается обновлением типа my_chat_member:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 |
{ "update_id": 123456789, "my_chat_member": { "chat": { "id": -987654321, "title": "Demo chat", "type": "group", "all_members_are_administrators": true }, "from": { "id": 23456789, "is_bot": false, "first_name": "Creator", "last_name": "I", "username": "I", "language_code": "uk" }, "date": 1674112937, "old_chat_member": { "user": { "id": 34567890, "is_bot": true, "first_name": "Reks", "username": "ReKSbizBot" }, "status": "left" }, "new_chat_member": { "user": { "id": 34567890, "is_bot": true, "first_name": "Reks", "username": "ReKSbizBot" }, "status": "member" } } } |
Значения "type": "group", "supergroup", "channel"
Значения "status": "creator", "member", "administrator", "left". !!! можно получить методом getChatMember, но если последний статус был "left", то чат больше боту не доступен, и API вернет ошибку #400: Bad Request: user not found.
При повышении привилегий до администратора свойство new_chat_member будет таким:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
"new_chat_member": { "user": {...}, "status": "administrator", "can_be_edited": false, "can_manage_chat": true, "can_change_info": true, "can_delete_messages": true, "can_invite_users": true, "can_restrict_members": true, "can_pin_messages": true, "can_promote_members": false, "can_manage_video_chats": true, "is_anonymous": false, "can_manage_voice_chats": true } |
//
|
1 2 3 4 5 6 7 8 9 10 11 |
{ "update_id": 123456789, "message": { "message_id": 1234, "from": {...}, "chat": {...}, "date": 1673269307, "contact": { "phone_number": "380678005000", "first_name": "u0412u0430u043bu0435u0440u0438u044f", "user_id": 1565449925}}} |
//
Обновление о публикации в канале
//
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
{ "update_id": 460399999, "channel_post": { "message_id": 123, "author_signature": "Dr", "sender_chat": { "id": -1001234567890, "title": "My channel", "type": "channel" }, "chat": { "id": -1001234567890, "title": "My channel", "type": "channel" }, "date": 1675627229, "text": "My content" } } |
Обновление о подписке бота в группу комментариев канала
//
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 |
{ "update_id": 460399008, "message": { "message_id": 5, "from": { "id": 1087968824, "is_bot": true, "first_name": "Group", "username": "GroupAnonymousBot" }, "sender_chat": { "id": -1001234567891, "title": "My channel comments", "type": "supergroup" }, "chat": { "id": -10012345678901, "title": "My channel comments", "type": "supergroup" }, "date": 1675628180, "new_chat_participant": { "id": 5336586007, "is_bot": true, "first_name": "Bot", "username": "myBot" }, "new_chat_member": { "id": 3456789012, "is_bot": true, "first_name": "Bot", "username": "myBot" }, "new_chat_members": [ { "id": 3456789012, "is_bot": true, "first_name": "Bot", "username": "myBot" } ] } } |
Обновление о подписке нового пользователя в чат
Обновление о комментарии к публикации в канале
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
{ "update_id": 460399009, "message": { "message_id": 6, "from": { "id": 1087968824, "is_bot": true, "first_name": "Group", "username": "GroupAnonymousBot" }, "sender_chat": { "id": -1001234567891, "title": "My channel comments", "type": "supergroup" }, "chat": { "id": -1001234567891, "title": "My channel comments", "type": "supergroup" }, "date": 1675628255, "message_thread_id": 4, "reply_to_message": { "message_id": 4, "from": { "id": 777000, "is_bot": false, "first_name": "Telegram" }, "sender_chat": { "id": -1001234567890, "title": "My chanel", "type": "channel" }, "chat": { "id": -1001234567891, "title": "My channel comments", "type": "supergroup" }, "date": 1675628144, "forward_from_chat": { "id": -1001234567890, "title": "My chanel", "type": "channel" }, "forward_from_message_id": 10, "forward_signature": "Dr", "is_automatic_forward": true, "forward_date": 1675628141, "text": "My content" }, "text": "My comment" } } |
Обновление о переходе чата в режим форума /group_chat_created
Переход group в режим форума приводит к автоматической миграции в новую supergroup, но обновление о переходе приходит до миграции
|
1 2 3 4 5 6 7 8 9 10 |
{ "update_id": 460399011, "message": { "message_id": 1234, "from": {...}, "chat": {...}, "date": 1675669917, "group_chat_created": true } } |
Обновление о миграции чата /migrate_to_chat_id, migrate_from_chat_id
При переходе чата из типа group в supergroup происходит через миграцию, о которой сообщает обновление из исходного чата:
|
1 2 3 4 5 6 7 |
{ "update_id": 460399013, "message": { ... "migrate_to_chat_id": -1001234567890 } } |
Затем из нового чата поступает обновление migrate_from_chat_id, со свойством sender_chat
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
{ "update_id": 460399014, "message": { "message_id": 1, "from": {...}, "sender_chat": { "id": -1001234567890, "title": "My supergroup", "type": "supergroup" }, "chat": {...}, "date": 1675669934, "migrate_from_chat_id": -123456789 } } |
Двум описанным обновлениям предшествует обновление my_chat_member.
Обновление о создании темы в форуме /forum_topic_created
//
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
{ "update_id": 460399016, "message": { "message_id": 333, "from": {...}, "chat": {...}, "date": 1675672040, "message_thread_id": 123, "forum_topic_created": { "name": "My new topic", "icon_color": 9367192 }, "is_topic_message": true } } |
Обновление о сообщении и ответе в теме форума
//
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
{ "update_id": 460399017, "message": { "message_id": 444, "from": {...}, "chat": {...}, "date": 1675672087, "message_thread_id": 123, "reply_to_message": { "message_id": 333, "from": {...}, "chat": {...}, "date": 1675672040, "message_thread_id": 123, "forum_topic_created": { "name": "My new topic", "icon_color": 9367192 }, "is_topic_message": true }, "text": "Hello, Ukraine!", "is_topic_message": true } } |
Обновление об ответе на сообщение в теме форума
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
{ "update_id": 460399019, "message": { "message_id": 555, "from": {...}, "chat": {...}, "date": 1675676761, "message_thread_id": 123, "reply_to_message": { "message_id": 444, "from": {...}, "chat": {...}, "date": 1675672087, "message_thread_id": 123, "text": "Hello, Ukraine!", "is_topic_message": true }, "text": "Glory to the Heroes!", "is_topic_message": true } } |
//
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. Режим разбора сущностей в тексте сообщения:
При любом режиме в результате выполнения метода будет сформирован массив сущностей 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-сериализазция объекта управляющего разметкой клавиатур |
Методы отправки файлов (фото, стикеры, аудио, медиа, документы и др.)
Существует три способа отправки файлов:
- Используя один из методов отправки указать в качестве источника строку с 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. Подробнее об отправке файлов »
|
| 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 объект:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
{ "ok": true, "result": { "message_id": 1234, "from": { ... }, "chat": { ... }, "date": 1662657439, "photo": [ { "file_id": "AgACAgQAAxkDAAIOZWO-4d5PiN3Wr0O983wkFkXCiIRrAAJbsDEbgZL8UVVlvZYBgxHGAQADAgADcwADLQQ", "file_unique_id": "AQADW7AxG4GS_FF4", "file_size": 1877, "width": 90, "height": 90 }, { "file_id": "AgACAgQAAxkDAAIOZWO-4d5PiN3Wr0O983wkFkXCiIRrAAJbsDEbgZL8UVVlvZYBgxHGAQADAgADbQADLQQ", "file_unique_id": "AQADW7AxG4GS_FFy", "file_size": 12075, "width": 200, "height": 200 }]}} |
Объект успешной отправки фото содержит объект 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 является объект:
|
1 2 3 4 5 6 |
{ "file_id": "AgACAgIAAxkDAAIE32QOCPG_yn5PeCyYUaq0FIqyzdAKAAKpxjEbK7pxSHLwLqDrNLF_AQADAgADeAADLwQ", "file_unique_id": "AQADqcYxGyu6cUh9", "file_size": 98445, "file_path": "photos\/file_0" } |
API не гарантирует сохранение исходного имени файла и mime-типа, но гарантируется доступность файла для загрузки не менее 1 часа по URL:
|
1 |
https://api.telegram.org/file/bot<token>/<file_path> |
Метод уведомления на обратный вызов /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 | один из идентификаторов области доступности:
|
| chat_id | Integer or String | Optional для области типа chat, chat_administrators или chat_member. id целевого чата или username целевой супергруппы (в формате @supergroupusername) |
| user_id | Integer | Optional для области типа chat_member. Уникальный идентификатор id целевого пользователя |
Пример установки двух команд в чате @matrix избранному пользователю:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
{ "method": "setMyCommands", "commands": [ { "command": "blue pill", "description" => "The story ends, you wake up in your bed..." }, { "command": "red pill", "description": "I show you how deep the rabbit hole goes." } ], "scope": { "type": "chat_member", "chat_id": "@matrix", "user_id": 11010010011011101100 }, "language_code": "en" } |
Метод удаления набора команд /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)
|
1 2 3 4 5 6 7 8 9 10 11 12 |
"caption_entities": [ { "offset": 0, "length": 24, "type": "bold" }, { "offset": 42, "length": 23, "type": "spoiler" } ] |
Разметка ответов /reply_markup
!!!
Разметка ответов является необязательным свойством отправляемого ботом сообщения, но это свойство отсутствует в результирующем объекте метода sendMessage.
Кнопки ответа reply_markup
Для отображения кнопок ответа в сообщение добавляется массив reply_markup с описанием разметки:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
{ 'chat_id' : 12345, 'text': 'Three Buttons in two rows: ', 'reply_markup':{ // разметка кнопок 'keyboard': [ [ // массив первой строки '1', '2', '3', '4', '5', '6', '7', '8', '9', '0' ], [ // массив второй строки 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L' ], 'one_time_keyboard' => true, // скрыть панель кнопок после нажатия 'resize_keyboard' => true // уменьшить панель кнопок, если будет возможно 'input_field_placeholder': 'Yes', // ? ] } } |
Клавиатура keyboard
Для відображення кнопок під повідомленням бота до повідомлення додається об'єкт reply_markup.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
{ 'chat_id' : 12345, 'text': 'Get three buttons in two rows in reply keyboard', 'reply_markup':{ // разметка кнопок 'keyboard': [ [ // массив первой строки [ 'Row 1, column 1', // ответ перовой кнопки 'Row 1, column 2 // ответ второй кнопки ] ], [ [ 'Row 2' ] ] ], 'one_time_keyboard': true, 'resize_keyboard': true } } |
//
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 в составе сообщения удаляет текущую клавиатуру ответов.
|
1 2 3 4 5 6 7 |
{ 'chat_id': 12345, 'message_id': 45678, 'reply_markup': { 'remove_keyboard': true } } |
Встроенные кнопки inline_keyboard
Для відображення кнопок під повідомленням бота до повідомлення додається об'єкт reply_markup, который содержит !!!.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
{ 'chat_id' : 12345, 'text': 'Three Buttons in two rows: ', 'reply_markup':{ // разметка кнопок 'inline_keyboard': [ [ // массив первой строки { // объект первой кнопки в строке 'text': 'Row 1, column 1', // надпись в кнопке 'callback_data': '11' }, // данные при нажатии { // объект второй кнопки в строке 'text': 'Row 1, column 2', 'callback_data': '12' } ], [ // массив второй строки { 'text': 'Row 2', 'callback_data': '2' } ] ] } } |
Каждое нажатие кнопки будет вызывать сообщение update с объектом callback_query структуры:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
{ "update_id": 23456, "callback_query": { "id": "4567890", "from": { пользователь }, "message": { // полностью повторяет сообщение содержащее нажатую кнопку "message_id": 123, "from": { ... }, "chat": { ... }, "date": 1662561700, "text": "Three Buttons in two rows: ", "reply_markup": { разметка кнопок } }, "chat_instance": "888888888888888888", "data": "11" // значение callback_data нажатой кнопки } } |
Отложенное сообщение
!!! по непроверенной гипотезе отправка сообщения отложенного до запланированного момента времени реализуется параметром 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) |
Возвращает объект чата в случае успеха:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
{ "ok": true, "result": { "id": -1001234567890, "title": "My supergroup", "type": "supergroup", "invite_link": "https:\/\/t.me\/+vjod-HiHiHaHaHai", "permissions": { "can_send_messages": true, "can_send_media_messages": false, "can_send_polls": false, "can_send_other_messages": true, "can_add_web_page_previews": true, "can_change_info": false, "can_invite_users": false, "can_pin_messages": false, "can_manage_topics": true }, "join_to_send_messages": true, "photo": { "small_file_id": "HIHAAgADGccxG58daUoACAIAA081oroW____gZhjbVE-PHwtBA", "small_file_unique_id": "HIHAGccxG58daUoAAQ", "big_file_id": "HIHAAgADGccxG58daUoACAMAA081oroW____gZhjbVE-PHwtBA", "big_file_unique_id": "HIHAGccxG58daUoB" } } } |
Полученные идентификаторы 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 в случае успеха.
|
1 2 3 4 |
{ "ok": true, "result": 123 } |
getChatMember
Метод getChatMember получает информацию об участнике чата. Способ гарантированно сработает для пользователей, только если бот является администратором в чате. Параметры метода:
| chat_id | Integer or String | Уникальный идентификатор целевого чата или имя пользователя целевой супергруппы или канала (в формате @channelusername) |
| user_id | Integer | Уникальный идентификатор целевого пользователя |
Возвращает объект ChatMember в случае успеха:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
{ "ok": true, "result": { "user": { "id": 123456789, "is_bot": false, "first_name": "ReKS", "last_name": "", "username": "ReKSbizBot", "language_code": "uk" }, "status": "administrator", "can_be_edited": false, "can_manage_chat": true, "can_change_info": true, "can_delete_messages": true, "can_invite_users": true, "can_restrict_members": true, "can_pin_messages": true, "can_manage_topics": true, "can_promote_members": false, "can_manage_video_chats": true, "is_anonymous": false, "can_manage_voice_chats": true } } |
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:
|
1 2 3 |
{ "ok": false, "parameters": { "retry_after": 40 }} |
Heap
editMessageMedia
sendMediaGroup
editMessageReplyMarkup применимо только к определению InlineKeyboard
createNewStickerSet
uploadStickerFile
Используйте этот метод, чтобы загрузить файл .PNG со стикером для последующего использования в методах createNewStickerSet и addStickerToSet (можно использовать несколько раз). Возвращает загруженный файл в случае успеха.
getChat
Источники
Пример связи 1С и мессенджера Telegram. Получение данных из 1С запросом из Telegram //infostart.ru