Telegram-бот на PHP

Несколько лет назад я сделал на своем сайте отправку сообщений в Telegram средствами серверного PHP. В конце статьи я упомянул, что кроме отправки данных можно организовать взаимодействие с сайтом через Telegram. Настало время это реализовать, то есть написать полноценного Telegram-бота на PHP.

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

Для того, чтобы серверный бот мог получать все сообщения и уведомления, первым делом надо зарегистрировать так называемый webhook, то есть указать ссылку на скрипт, куда Telegram будет отправлять все данные. Формируем ссылку вида:

https://api.telegram.org/bot[token]/setWebhook?url=https://вашсайт.ру/telebot.php
где [token] - это токен, полученный при регистрации бота. Например, для описанного ранее тестового бота ссылка будет вот такой:

https://api.telegram.org/bot629705209:AAFhFqFbhR3VHHrOgOM7R4OnQT-usqJwTBk/setWebhook?url=https://вашсайт.ру/telebot.php
Если все сделано правильно, то в браузере будет получен ответ:

{"ok":true,"result":true,"description":"Webhook was set"}
Telegram отправляет данные на указанный скрипт при помощи POST-запроса, формат передаваемых данных всегда JSON. Для удобства разбора полетов, особенно на первых этапах, лучше логировать все полученные данные куда-нибудь в файл. Каркас скрипта-приемника будет иметь следующий вид:Тут сразу же выполняется быстрая проверка на корректность полученных данных, после чего разобранный запрос помещается в массив $json. Обычно бот может получать текстовые данные, файлы или управляющие команды. Начнем с самого простого. Когда пользователь пишет в чат сообщение, то бот получит примерно такие данные:

Array (
  [update_id] => 434540657
  [message] => Array (
    [message_id] => 1702
    [from] => Array (
      [id] => 698237240
      [is_bot] =>
      [first_name] => Dmitry
      [language_code] => ru
    )
    [chat] => Array (
      [id] => 698237240
      [first_name] => Dmitry
      [type] => private
    )
    [date] => 1679039931
    [text] => Привет
  )
)
В зависимости от функционала и назначения, бот самостоятельно анализирует входящее сообщение, на его основании выполняет какие-то действия и, если надо, отправляет пользователю ответ. Отправлять данные мы уже умеем. По такой схеме работают, например, боты-переводчики.

Бот может принимать управляющие команды, они начинаются с косой черты "/". Если Telegram распознает такую команду, то в этом случае в уведомлении будет присутствовать дополнительный блок, хотя в остальном оно ничем не отличается от обычного текстового сообщения.

Array (
  [update_id] => 434540657
  [message] => Array (
    [message_id] => 1702
    [from] => Array (
      [id] => 698237240
      [is_bot] =>
      [first_name] => Dmitry
      [language_code] => ru
    )
    [chat] => Array (
      [id] => 698237240
      [first_name] => Dmitry
      [type] => private
    )
    [date] => 1679039931
    [text] => /dosomething
    [entities] => Array (
      [0] => Array (
        [offset] => 0
        [length] => 12
        [type] => bot_command
      )
    )
  )
)
Тут указывается, с какой позиции сообщения начинается управляющая команда и какой она длины. Реакция на ту или иную команду, естественно, остается на совести разработчика бота. Пользователь может передавать несколько команд в одном сообщении, даже перемежая их текстом. Telegram поможет их определить и для каждой команды передаст ее позицию в отправленном сообщении и длину.

Array (
  [update_id] => 434540657
  [message] => Array (
    [message_id] => 1702
    [from] => Array (
      [id] => 698237240
      [is_bot] =>
      [first_name] => Dmitry
      [language_code] => ru
    )
    [chat] => Array (
      [id] => 698237240
      [first_name] => Dmitry
      [type] => private
    )
    [date] => 1679039931
    [text] => Yo, bota! /krush /kill and /destroy
    [entities] => Array (
      [0] => Array (
        [offset] => 10
        [length] => 6
        [type] => bot_command
      )
      [1] => Array (
        [offset] => 17
        [length] => 5
        [type] => bot_command
      )
      [2] => Array (
        [offset] => 27
        [length] => 8
        [type] => bot_command
      )
    )
  )
)
Когда пользователь отправляет боту картинку со своего устройства, то фактически боту никаких файлов не передается. Файл загружается на сервер Telegram, а боту приходит информация об этом файле.

Array (
  [update_id] => 434540657
  [message] => Array (
    [message_id] => 1702
    [from] => Array (
      [id] => 698237240
      [is_bot] =>
      [first_name] => Dmitry
      [language_code] => ru
    )
    [chat] => Array (
      [id] => 698237240
      [first_name] => Dmitry
      [type] => private
    )
    [date] => 1679039931
    [photo] => Array (
      [0] => Array (
        [file_id] => AgAAAAAA1111111222222444zF-06666667777DDDDD
        [file_unique_id] => AQ111111111111h4
        [file_size] => 1575
        [width] => 55
        [height] => 90
      )
      [1] => Array (
        [file_id] => AgAAAAAA1111111222222444zF-06666667777CCCCC
        [file_unique_id] => AQ111111111111hy
        [file_size] => 23882
        [width] => 197
        [height] => 320
      )
      [2] => Array (
        [file_id] => AgAAAAAA1111111222222444zF-06666667777BBBBB
        [file_unique_id] => AQ111111111111h9
        [file_size] => 99568
        [width] => 493
        [height] => 800
      )
      [3] => Array (
        [file_id] => AgAAAAAA1111111222222444zF-06666667777AAAAA
        [file_unique_id] => AQ111111111111h-
        [file_size] => 175335
        [width] => 789
        [height] => 1280
      )
    )
  )
)
Как видите, Telegram и тут позаботился о web-мастере, передавая не только оригинальное изображение, но и подготовив аж три превьюшки разного размера. Сам файл получается в два этапа. Сперва надо определить, какой из четырех файлов нам нужен, они отличаются по полю file_id. Допустим, превьюшки нас не интересуют, поэтому просто берем последний элемент массива и получаем информацию о загруженном файле, используя его идентификатор.Если все сделано правильно, то будет получен ответ примерно такого содержания:

Array (
  [ok] => 1
  [result] => Array (
    [file_id] => AgAAAAAA1111111222222444zF-06666667777AAAAA
    [file_unique_id] => AQ111111111111h-
    [file_size] => 175335
    [file_path] => photos/file_0.jpg
  )
)
Только теперь, получив имя файла, можно загрузить его содержимое с сервера Telegram. Код будет примерно таким:Есть большой соблазн вообще пропустить предыдущий шаг, так как массив изображений формируется только для файлов в формате JPEG, а оригинальная картинка всегда хранится по пути photos/file_0.jpg. Но стопроцентной гарантии у меня нет, поэтому оставлю это на ваше усмотрение.

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

Array (
  [update_id] => 434540657
  [message] => Array (
    [message_id] => 1702
    [from] => Array (
      [id] => 698237240
      [is_bot] =>
      [first_name] => Dmitry
      [language_code] => ru
    )
    [chat] => Array (
      [id] => 698237240
      [first_name] => Dmitry
      [type] => private
    )
    [date] => 1679039931
    [document] => Array (
      [file_name] => my_image.png
      [mime_type] => image/png
      [thumbnail] => Array (
        [file_id] => AgAAAAAA1111111222222444zF-06666667777CCCCC
        [file_unique_id] => AQ111111111111hA
        [file_size] => 25093
        [width] => 320
        [height] => 282
      )
      [thumb] => Array (
        [file_id] => AgAAAAAA1111111222222444zF-06666667777BBBBB
        [file_unique_id] => AQ111111111111hB
        [file_size] => 25093
        [width] => 320
        [height] => 282
      )
      [file_id] => AgAAAAAA1111111222222444zF-06666667777AAAAA
      [file_unique_id] => AQ111111111111hC
      [file_size] => 33560
    )
  )
)
Остальные документы считаются бинарными файлами и передаются как есть.

Array (
  [update_id] => 434540657
  [message] => Array (
    [message_id] => 1702
    [from] => Array (
      [id] => 698237240
      [is_bot] =>
      [first_name] => Dmitry
      [language_code] => ru
    )
    [chat] => Array (
      [id] => 698237240
      [first_name] => Dmitry
      [type] => private
    )
    [date] => 1679039931
    [document] => Array (
      [file_name] => my_book.fb2
      [mime_type] => application/octet-stream
      [file_id] => AgAAAAAA1111111222222444zF-06666667777AAAAA
      [file_unique_id] => AQ111111111111hC
      [file_size] => 1236900
    )
  )
)
Содержимое файла получается точно так же в два захода. И вот тут от получения информации о файле уже не отвертеться.Дальше содержимое файла записывается на диск или используется по иному назначению. Хорошим тоном будет уведомить пользователя о факте успешного получения файла и о действии, которое с этим файлом было выполнено.

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

Для формирования объекта файла я не использую функции cURL, так как функция curl_file_create запросто может оказаться недоступной, особенно на виртуальном хостинге. Ручками надежнее. Отправка документа выполняется почти так же, только меняется ключ массива и ссылка API.


По аналогии отправляются аудиофайлы, вынесенные от документов в отдельную категорию.

Отправку всяких стикеров, контактов и прочего смотрите в официальной документации, там ничего сложного.

Отдельно хочется остановиться на взаимодействии пользователя с ботом. Конечно, можно сколько угодно набирать вручную текстовые сообщения и команды управления, но это быстро надоедает, к тому же повышается риск ошибки. Гораздо удобнее сразу же предоставлять пользователю список возможных действий в привычном ему формате, например, в виде кнопок.

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

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

Array (
  [update_id] => 434540657
  [callback_query] => Array (
    [id] => 1111222223333344444
    [from] => Array (
      [id] => 698237240
      [is_bot] =>
      [first_name] => Dmitry
      [language_code] => ru
    )
    [message] => Array (
      [message_id] => 74
      [from] => Array (
        [id] => 1112223445
        [is_bot] => 1
        [first_name] => MySupaTestBot
        [username] => MySupaTestBot_bot
      )
      [chat] => Array (
        [id] => 698237240
        [first_name] => Dmitry
        [type] => private
      )
      [date] => 1679227556
      [text] => Вот такие кнопки. Попробуй их все!
      [reply_markup] => Array (
        [inline_keyboard] => Array (
          [0] => Array (
            [0] => Array (
              [text] => Перейти на сайт
              [url] => https://www.manhunter.ru/
            )
          )
          [1] => Array (
            [0] => Array (
              [text] => Привет
              [callback_data] => Нажата внопка 1
            )
            [1] => Array (
              [text] => До свидания
              [callback_data] => Нажата внопка 2
            )
          )
        )
      )
    )
    [chat_instance] => -123456789081123230
    [data] => Нажата внопка 1
  )
)

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

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

И напоследок буквально пару слов об оформлении сообщений, которые бот отправляет пользователю. Чтобы определенный фрагмент текста можно было скопировать одним нажатием, его надо оформить тегами <code> и дополнить список полей отправки параметром parse_mode=HTML.По умолчанию Telegram не позволяет вставлять изображения в текст сообщений. Это частично можно обойти, сформировав сообщение особым образом, указав ссылку на картинку с пустым текстом ссылки и добавив еще один параметр disable_web_page_preview=false в отправляемые данные.


В этом случае превью изображения будет расположено сразу под текстом, независимо, где оно находилось в оригинале. И такая превьюшка в сообщении может быть только одна. Что ж, это лучше, чем ничего.Еще один часто используемый вариант оформления постов - большой текст в качестве подписи к изображению. В этом случае картинка будет сверху, а под ней, например, рекламный текст. Длина подписи к картинке, а, следовательно, и текста поста, не должна превышать 1024 символа. Обычный текст сообщения к фото добавлять нельзя.


Пост можно дополнить инлайновыми кнопками-ссылками, украсить иконками эмодзи, главное во всем знать меру. Код для отправки будет следующим:Комбинируя описанные тут методы приема и отправки сообщений разного типа, вы можете написать собственного Telegram-бота с нужным функционалом. В очередной раз скажу, что перечисленными функциями возможности Telegram-ботов не ограничиваются. Изучайте документацию, смотрите примеры, пробуйте и у вас все получится.

Комментарии

Добавить комментарий

Для вставки цитаты выделите текст и нажмите сюда

Имя*:

Текст комментария (не более 2000 символов)*:

*Все поля обязательны для заполнения.

Комментарии, содержащие рекламу, ненормативную лексику, оскорбления и т.п., а также флуд и сообщения не по теме, будут удаляться. Нарушителям может быть заблокирован доступ к сайту.