DroidScript
DroidScript
учимся и разрабатываем

Методы Bot Api

Ботостроительство  
09.12.2024

Документация к ТГ написано неплохо, но вызывает некоторое удивление реализация работы с ней. Это мы исправим при помощи браузерного скрипта, после чего всё станет намного удобнее.

Запустим "обезьяну" в браузер, которая подаст нам документацию в удобном для работы виде. Для этого установите в браузере плагин Tampermonkey, создайте скрипт с кодом ниже и включите скрипт.

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

У нас есть две отличные новости: большая часть параметров в методах является необязательной, а многие методы являются вариацией базового метода. Например, разобравшись с методом отправки текстовых сообщений sendMessage, будет намного проще разобраться с 15 другими методами send. Прямо как при игре на гитаре. Научился играть один вид аккорда с баррэ - умеешь играть 12.

Запросы к серверу ТГ производятся по протоколу https. Поддерживаются методы GET и POST, и аж четыре способа передачи параметров. Из всего предлагаемого разнообразия выберем метод POST и формат передачи с использованием JSON. Этот формат удобно использовать при работе с древовидными структурами данных и детально о нём поговорим на следующем занятии.

С учётом выбранного способа отправки запросов общая схема будет выглядеть так:

  • В строке запроса указываем строку в виде сервер/токен бота/метод, например, https://api.telegram.org/bot123:ABC.../sendMessage
  • В теле запроса указываем параметры в формате JSON

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

Для данного метода нужно указать два обязательных параметра - chat_id и text. В конце прошлого занятия мы договорились в ТГ создать свой приватный канал и добавить в него бота администратором. Если с этим возникли сложности, то пара подсказок. Канал создаётся по команде бокового меню вашего профиля, а добавления бота в канал производится по ссылке Администраторы в диалоге информации о канале.

В документации написано, что в параметре chat_id можно указать имя канала с собачкой перед ним. Для присвоению каналу имени его нужно сделать публичным. Предположим, свободно имя xxx_ch. Тогда в значении параметра chat_id нужно будет написать "@xxx_ch".

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

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

Отправьте в канал любой пост, щелкните правой кнопкой мыши на нём и скопируйте ссылку на пост. Она будет иметь вид https://t.me/Число 1/Число 2. Возьмите Число 1 и добавьте перед ним -100 - это и будет ID канала вида -100123.... Число 2 - номер поста, который также вскоре нам потребуется. С учётом сказанного запишем параметры для запроса sendMessage:

{
  "chat_id": -100123...,
  "text":"Новый пост"
}

Вид запроса в программе Postman.

POST-запрос sendMessage

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

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

POST-запрос sendMessage

Переменные создаются на вкладке Environments и в запросах указываются в двойных фигурных скобках {{Имя переменной}}

Ниже показан пример запроса с переменными:

https://api.telegram.org/bot{{TOKEN}}/sendMessage

{
  "chat_id": {{chatId}},
  "text":"Новый пост"
}

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

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

Пересылка сообщения forwardMessage

Этот метод требует три параметра - chat_id - ID целевого чата, в который будет переслано сообщение, from_chat_id - ID чата, из которого нужно переслать сообщение, message_id - идентификатор сообщения (его номер). Перешлем сообщение себе, указав один и тот же ID для chat_id и from_chat_id.

{
  "chat_id": -100123...,
  "from_chat_id": -100123...,
  "message_id":Число
}

Копирование сообщения copyMessage

Здесь всё аналогично предыдущему методу. Нужно только в строке запроса вместо forwardMessage указать copyMessage. Имена методов нечувствительны к регистру и можно написать copymessage. Но так имя хуже воспринимается и сложнее проверить правильность его написания.

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

  • Собрать chat_id подписчиков в текстовой файл или базу
  • Составить пост для рассылки в личной папке
  • После проверки переслать пост боту. Пересылка позволит проконтролировать то, как сообщение скопируется. Нюансы бывают и будет досадно, если вместо кружочка пользователи получат черный круг.
  • Разослать ботом данное сообщение по подписчикам
{
  "chat_id": -100123...,
  "from_chat_id": -100123...,
  "message_id": ID сообщения
}

Добавление реакции в сообщение setMessageReaction

Здесь появляется новый параметр reaction - массив объекта эмоций c двумя полями. Для не премиум-подписки доступна установка одной реакции.

{
  "chat_id": -100123...,
  "message_id": Число,
  "reaction": [
    {
      "type": "emoji",
      "emoji": "🔥"
    }
  ]
}

Закрепление сообщения pinChatMessage

{
  "chat_id": -100123...,
  "message_id": Число
}

Редактирование текста сообщения editMessageText

Этот метод находится в разделе Updating messages. Он не работает с пересланными сообщениями.

{
  "chat_id": -100123...,
  "message_id": Число,
  "text":"Это новый текст"
}

Думаю, теперь вы сможете без труда самостоятельно выполнить и другие доступные методы. Если повезёт, вы не столкнётесь с "хитрыми" методами, которые имеют привязку по времени. Мы с ними также разберёмся, но позже. А на следующем занятии засучим рукава и погрузимся в JSON, после чего сможем создавать клавиатуры с тучей кнопок и по полной программе использовать дополнительные параметры в запросах.

Ботостроительство  
© 2016-2025 
actech