Створення чат-бот Telegram на PHP. Частина друга

Стаття також доступна російською (перейти до перегляду).

Зміст:

• Структура повідомлення (відповідь від Bot API)
• Робота з повідомленнями. Кнопки
  • Виконання підготовчих операцій на хостингу розробки
  • Структура файлу PHP-сценарію
  • Формування та відправлення текстових повідомлень
  • Робота з кнопками
• Робота з файлами та зображеннями

У попередній статті нами були розглянуті основні компоненти робочого середовища чат боту та їх взаємодія. Тепер зосередимося на методах управління інтерфейсом та роботі чат боту за допомогою інструментарію SDK для платформи PHP. Їх використання надає можливість створювати гнучкі та багатофункціональні додатки, не ускладнюючи при цьому структуру. Теоретичні викладки будуть супроводжуватися практичними прикладами.

Структура повідомлення (відповідь від Bot API)

При формуванні відповіді по каналу HTTP на будь-який API запит сервер Телеграм (Bot API) використовує формат JSON для опису типів даних та їх значень, котрі передаються. Це дозволяє універсалізувати відповідь та отримати широкі можливості для її обробки на стороні клієнта.

Склад JSON-об’єктів, котрі присутні у відповіді серверу визначається набором методів запиту, котрі можуть бути різними. Методи та їх параметри детально описані у документації до Bot API. Наведемо декотрі з методів, що найбільш використовуються:

GetWebhookInfo() – запит на отримання значень параметрів об’єкту WebhookInfo – ip_address, url, max_connections та інші.

GetUpdates() – запит на отримання вхідних оновлень шляхом виконання опитів типу Long Polling, при цьому повертається масив об’єктів Update та їх значення – message, update_id, message_reaction та інші.

GetMe() – запит на отримання основної інформації про бот у вигляді значень параметрів User-об’єкту – is_bot, id, first_name, username, language_code та інші.

GetMessageId() – запит на отримання унікального ідентифікатору повідомлення для визначеного чату.

 Наведемо приклад структури повідомлення, котре надходить від серверу Телеграм до модулю розробки при зверненні до боту з боку стороннього користувача. Складові цієї структури відповідають параметрам об'єкту Message, описаного у документації Bot API.

Код буде наступним:

 "ok": true, // Показник успішності виконання запиту

  "result": { // Повернення масиву об’єктів та їх значень

"message_id": 30, // Номер повідомлення

"from": { // Дані про відправника повідомлення

  "id": 7350793xxx,

  "is_bot": false,

  "first_name": "Programmer75",

  "username": "programmer75",

  "language_code": "en-UK"

},

"chat": { // Відомості про чат, до котрого потрапило повідомлення

  "id": 7350793xxx,

  "first_name": "Programmer75",

  "username": "programmer75",

  "type": "private"

},

"date": 1637907910, // Дата створення повідомлення

"text": "Greetings from America!" // Вміст повідомлення

  }

У випадку отримання наведеної відповіді від серверу, необхідно «витягти» з неї значення потрібних об’єктів, основними з яких у даному випадку є First Name, Chat id та Text message. Це дасть змогу сформувати відповідь користувачу, котрий звернувся до нашого бота. 

Перед тим, як використовувати отримані значення параметрів у сценаріях PHP, попередньо необхідно декодувати відповідні JSON-об’єкти за допомогою стандартних засобів PHP. Пізніше продемонструємо, як це можна зробити.

Робота з повідомленнями. Кнопки

Виконання підготовчих операцій на хостингу розробки

Перед початком створення PHP-сценарію по управлінню роботою чат боту необхідно виконати наступні кроки:

1. Під'єднатися по SSH до віртуального, VPS- або іншого серверу із підтримкою PHP та доступом в Інтернет;
2. Оновити версію PHP до 8.0 або вище;
3. Перейти до каталогу свого веб-сайту для розробки чат-ботів ($ cd ~/bot-development.com/www);
4. Встановити бібліотеку Telegram Bot SDK ($ composer require telegram-bot-sdk/telegram-bot-sdk) – для версій SDK 4.х;
5. Налагодити автоматичне оновлення версій бібліотеки. Для цього у файл composer.json необхідно додати наступний рядок:

   "require": {
        "telegram-bot-sdk/telegram-bot-sdk": "^4.0",
              }
   

   При необхідності використання розширення для Фреймворку Laravel, до вказаної конструкції слід додатково додати наступну строчку: "telegram-bot-sdk/laravel": "^4.0".
6. Створити файл сценарію та зберегти його у поточному каталогу. Слід зазначити, що сценарій, котрий викликається через веб-хук повинен бути доступним по HTTP. Усі інші файли - необов’язково.

Структура файлу PHP-сценарію

Структура файлу сценарію буде напряму залежати від версії SDK-бібліотеки та режиму роботи з нею. Для версій SDK 3.х або 4.х при використанні локального режиму розробки додатку phpStandalone, структура файлу сценарію буде мати наступний вигляд:

При використанні Фреймвору Laravel можливі два режими роботи:

• Із використанням класу Facade;

• Із використанням Служби контейнерів.

Використання класу Facade. У цьому випадку структура файлу змінюється наступним чином:

Використання Служби контейнерів. У цьому разі сценарій для отримання даних останнього повідомлення буде виглядати наступним чином:

Формування та відправлення текстових повідомлень

Наведемо приклад формування та відправлення повідомлення від чат боту, при цьому будемо вважати, що змінна $telegram вже активована одним із наведених раніше способами. У такому випадку код буде виглядати наступним чином:

$response_1 = $telegram->sendMessage([
   	'chat_id' => 'CHAT_ID',
   	'text' => 'Greetings from Ukrainian developers!'
 ]); // Повідомлення, що передається

 $messageId = $response_1->getMessageId(); // Збереження унікального у межах чату ідентифікатору повідомлення

Робота з кнопками

Telegram Bot API надає можливість розробникам ботів разом із повідомленнями формувати та відправляти набір кнопок або клавіатур, котрі будуть відображатися в інтерфейсі користувача, котрий спілкується із ботом. При натисканні на певну кнопку, відправляється визначена команда, що значно спрощує спілкування користувача із ботом.   

На даний час Bot API підтримує три варіанти клавіатур:

• «Звичайна» або та, що настроюється – до кожної з її кнопок «прив’язані» наперед визначені відповіді або команди. Реалізується за допомогою об’єкту ReplyKeyboardMarkup;

• «Прив’язана до повідомлення» – відображається разом із повідомленням, котрому вона належить. Реалізується за допомогою об’єкту InlineKeyboardMarkup;

• «Для видалення клавіатури» поточного чату. Реалізується за допомогою об’єкту ReplyKeyboardRemove.

Нижче наведені зазначені вище варіанти клавіатур.

Розглянемо перший з наведених варіантів та спробуємо реалізувати його на практиці за допомогою відповідного сценарію.

Об’єкт ReplyKeyboardMarkup має наступні параметри:

Resize_keyboard – дає змогу змінювати розмір клавіатури по висоті. За замовчуванням параметр відключений і, відповідно, висота користувацької клавіатури співпадає зі стандартним розміром клавіатури для поточного додатку.

One_time_keyboard – дає змогу користувачу тимчасово приховати клавіатуру.

Selective – дає можливість відображати клавіатуру лише для визначених користувачів. 

Keyboard – Обов’язковий. Представляє набір кнопок, кожна з яких визначається параметрами об’єкту KeyboardButton. 

Для режиму розробки phpStandalone код сценарію буде виглядати наступним чином:

Робота з файлами та зображеннями

Сформуємо повідомлення для відправлення нашим ботом файлу зображення із ім’ям my_image.jpg:

$response_3 = $telegram->sendPhoto([
   	'chat_id' => 'CHAT_ID',
   	'photo' => 'path/to/my_image.jpg', // Вказуємо локальний шлях до файлу зображення та його ім’я
   	'caption' => 'Happy New Year greetings' // Формування підпису до зображення
 ]);

 $messageId = $response_3->getMessageId(); // Збереження ідентифікатору повідомлення

У випадку, якщо нам потрібно передати файл, котрий знаходиться за будь-якою URL-адресою, строчка із параметром photo наведеного коду зміниться наступним чином:

'photo' => 'http://photo-gallery.com/photos/my_image.jpg' // URL файлу 	

Всі інші конструкції залишаються без змін.

Сподіваюсь, наша стаття по створенню телеграм-бота була корисною для Вас. В залежності від очікуваної кількості запитів на сервер для розміщення боту можно скористатися віртуальним хостингом, VPS, або виділеним сервером. Під час експлуатації боту, по мірі збільшення навантаження тип послуги можно змінити. 

Підписуйтесь на наш телеграм-канал https://t.me/freehostua, щоб бути в курсі нових корисних матеріалів.

Дивіться наш канал Youtube на https://www.youtube.com/freehostua.

Ми у чомусь помилилися, чи щось пропустили?

Напишіть про це у коментарях, ми з задоволенням відповімо та обговорюємо Ваші зауваження та пропозиції.