Создание Telegram бота на PHP #1: основные понятия для работы с API / Habr

Всем привет, это первый урок из курса по разработке ботов для Telegram. В данном курсе, мы с вами разберём как создавать ботов для Telegram на PHP. Я расскажу вам как отправлять текстовые сообщения, как отправлять файлы, как получать и обрабатывать сообщения от пользователей и по итогу мы с вами напишем скрипт для быстрого создания бота для Telegram на PHP.

В первом уроке мы с вами рассмотрим основные понятия связанные с API. Я вам расскажу что такое API методы, хуки, покажу на примере Telegram построение URL для создания запросов и расскажу о том как создаются простые API запросы на PHP.

Полный список всех записей курса находится на сайте или в публикациях на Хабр.

Для отправки и получения запросов через API, вам лучше использовать виртуальный хостинг, так как локальный хостинг не сможет получать данные через хуки.

Основные понятия

Давайте рассмотрим основные понятия для работы с API.

API (Application Programming Interface) — это набор способов и правил, по которым различные программы общаются между собой и обмениваются данными.

Метод API — это определённое действие, которое должно выполнить приложение основываясь на полученных данных (отправить сообщение, вернуть список чатов, отправить картинку и т.д.)

Token (токен) — это уникальный ключ бота, необходимый для отправки запросов.

Как отправлять HTTP запросы на PHP

Для отправки HTTP запросов можно использовать функцию file_get_contents(), где в качестве первого главного параметра указывается ссылка. Данная функция отлично подходит для отправки GET запросов, но к сожалению с помощью функции file_get_contents() нельзя отправлять POST запросы и поэтому для отправки POST запросов мы будем использовать библиотеку Curl.

Curl — это библиотека предназначенная для получения и передачи данных через такие протоколы, как HTTP, FTP, HTTPS.

Подробнее о Curl вы можете почитать на моём сайте.

Виды взаимодействия с приложением через API

Существует 2 вида взаимодействия с приложением через API. Первое это от клиента к серверу, а второе от сервера к клиенту. Клиентом в данном случае является ваше приложение (сайт), а в качестве сервера выступает сайт на который вы отправляете запросы (в нашем случае, это Telegram).

API запрос — это способ общения с программой, по средствам отправки данных от клиента — серверу.

Hooks (Хуки) — это способ общения с программой, по средствам отправки данных от сервера — клиенту. То есть при определённых изменениях в программе, сервер (приложение) будет отправлять данные на указанный скрипта клиента.

Документация для работы с API Telegram

Все методы и параметры для запросов вы можете найти в официальной документации Telegram.

Telegram Bot API — https://core.tlgr.org/bots/api

К данному сайту мы будем ссылаться на протяжение всего курса.

Работа с документацией для Telegram

Документация для создания Telegram ботов разделена на несколько разделов.

В разделе Recent changes вы можете найти информацию об обновлениях Telegram. Здесь описаны версии и нововведения которые были внесены в функционал мессенджера.

Разделы Authorizing your bot и Making requests описывают способы авторизации ботов и способы создания запросов для работы с ботами.

Раздел Getting updates описывает способы получения обновлений взаимодействия с ботами. При взаимодействие пользователя с ботов, все его действия, по стандарту, записываются на сервера Telegram, и для того чтобы получить к ним доступ, необходимо отправить запрос getUpdates.

Отправив запрос getUpdates вы можете получить id последнего пользователя который написал боту, узнать его ник, текст сообщения и дату отправки. Если бот добавлен в сообщество, то вы можете получить id сообщества.

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

Следующий раздел, который нас интересует называется — Available types. Данный раздел описывает все типы данных которые возвращает нам Telegram. Когда ваш скрипт отправляет запрос, то обработав его, Telegram вернёт вам ответ в формате JSON строки, в котором описаны специальные параметры.

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

Далее описан раздел, с которым нам придётся работать больше всего — это Available methods, методы для взаимодействия с ботом. Советую вам пройтись по всем методам и изучить все возможности работы с ботами.

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

Ну и в конце у нас описаны методы для работы со стикерами, играми в Telegram, методы для работы с оплатой в Telegram.

Структура URL для отправки запросов в Telegram

API Telegram имеет простую и понятную структуру урлов для отправки запросов.

Вот пример URL для создания запросов к боту:

https://api.telegram.org/bot{token}/{method}

{token} — это уникальный ключ, который выдаётся при создание бота;

{method} — это метод запроса по которому мы будем получать или отправлять определённые данные. В зависимости от названия метода, мы будем выполнять разные действия.

Примеры URL для запросов

Данные примеры используются только для наглядности построения URL, токен указанный в URL не привязан ни к одному боту!

Вот так выглядит отправка сообщений методом GET. Первая часть URL содержит домен api.telegram.org, далее прописываем строку bot с токеном который нам даётся при создание бота, после чего указываем метод sendMessage и перечисляем GET параметры.

https://api.telegram.org/bot546445612928:AAHjk6643OYgWHim_TICgsaF9NDDVXYnKzA/sendMessage?chat_id=<ID чата>&text=<text>

Отправка файлов в чат выглядит аналогично, только метод sendMessage заменяется на sendDocument. И здесь не перечисляются GET параметры, после указания метода, так как мы отправляем данные методом POST.

https://api.telegram.org/bot543264456928:AAHjk6643OYgWHim_TICgsaF9NDDVXYnKzA/sendDocument

Отправка изображений в чат:

https://api.telegram.org/bot546413456928:AAHjk6643OYgWHim_TICgsaF9NDDVXYnKzA/sendPhoto

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

Второй урок уже на Хабре - https://habr.com/ru/post/697000/