Создание Telegram бота на PHP #1: основные понятия для работы с API
Всем привет, это первый урок из курса по разработке ботов для 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
Документация для создания 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 для создания запросов к боту:
— это уникальный ключ, который выдаётся при создание бота;
— это метод запроса по которому мы будем получать или отправлять определённые данные. В зависимости от названия метода, мы будем выполнять разные действия.
Примеры URL для запросов
Данные примеры используются только для наглядности построения URL, токен указанный в URL не привязан ни к одному боту!
Вот так выглядит отправка сообщений методом GET. Первая часть URL содержит домен api.telegram.org, далее прописываем строку bot с токеном который нам даётся при создание бота, после чего указываем метод sendMessage и перечисляем GET параметры.
https://api.telegram.org/bot546445612928:AAHjk6643OYgWHim_TICgsaF9NDDVXYnKzA/sendMessage?chat_id=
How To Make Admin Panel In Telegram Avanced Bot || How To Make Admin Panel In Coding Bot
Конструкторы соответствующих классов в качестве аргументов требуют соответствующие обязательные параметры. При установке необязательных аргументов можно использовать цепочки методов, например:
$message = (new FSATelegramSendDice($chat_id, 1))->setDisableNotification()->setProtectContent();
Если в запросе необходимо прикрепить файл, то сделать это можно с помощью CURLFile , в том числе через процедурный стиль:
$file = curl_file_create(realpath(‘my_photo.jpg’));
Выполнение запросов на сервер
Запросы на сервер выполняются с помощью методов httpGet() , httpPost() или httpPostJson() . При этом необходимо установить токен доступа и прокси, если необходим, в конструкторе FSATelegramQuery .
$webhook = new FSATelegramWebhook; $update = $webhook->getUpdate();
Данные можно получить в сыром виде:
$update = $webhook->getUpdateRaw();
Получать данные запроса можно любое число раз. Оригинальный запрос сохраняется внутри класса и используется при последующих запросах.
Ответ на WebHook может быть выполнен с помощью метода replyJson().
$webhook = new FSATelegramWebhook(); $reply=new FSATelegramSendMessage($chat_id, «Привет»); $webhook->replyJson($reply);
Отправить ответ можно только один раз. После отправки ответа работа скрипта будет остановлена.
При необходимости Update можем быть разобран на сущности. Все необходимые сущности собраны в пространстве имён Entity .
$webhook = new FSATelegramWebhook; $update = new FSATelegramEntityUpdate($webhook->getUpdate());
Операция разбора всего Update выполняется довольно медленно, поэтому можно обойтись разбором только нужных частей, например, User , для использования в MessageEntity :
$user = new FSATelegramEntityUser($update->callback_query->message->from); $message_entity->setUser($user);
Также можно использовать классы из пространства имён Entity в IDE для формирования подсказок без непосредственного использования.
Вспомогательный класс Helper
Позволяет быстро настроить взаимодействие с серверами телеграм. Перед использованием нужно инициализировать класс:
FSATelegramHelper::init($config);
$config — массив с параметрами инициализации:
- $config[‘token’] — ваш ключ Telegram Bot API, обязательный параметр;
- $config[‘proxy’] — адрес прокси, если необходим;
- $config[‘api_url’] — адрес Local Bot API сервера, если необходимо.
Параметры могут содержать и другие ключи, значение которых можно будет получить через getConfigVar() с указанием имени параметра:
$admin_id = FSATelegramHelper::getConfigVar(‘admin_id’);
Если параметр не задан в массиве, то будет возвращён null.
Отправка запросов на сервер
Получение экземпляра FSATelegramQuery и отправка запросов на сервер:
FSATelegramHelper::query()->httpGet($query); FSATelegramHelper::query()->httpPost($query); FSATelegramHelper::query()->httpPostJson($query);
Получение экземпляра FSATelegramWebhook и данных запроса:
FSATelegramHelper::webhook()->getUpdate();
При первом получении экземпляра FSATelegramWebhook устанавливается обработчик исключений. Данные об ошибках при обработке Webhook будут отправлены администратору на аккаунт в телеграм, если он указан в массиве параметров инициализации в ключе admin_id . Чтобы пользователь смог получать сообщения об ошибках необходимо указать его chat_id с помощью метода:
FSATelegramHelper::setExceptionChatId($chat_id);
После этого при возникновении исключения пользователь в $chat_id будет оповещён о проблеме. Текст исключения UserException из любого пространства имён будет передан пользователю без изменения. При других типах исключений пользователю будет сообщено об ошибке, при этом будет отправлено оповещение на учётную запись администратора (если он был указан).
Источник: laptopprocessors.ru
Wiki Robot
Wiki Robot can post text to chat on scheduled time. You can setup multiple text and configure specific post time for each text. In any time you can also display text using its ID.
Install
Step 2. Give bot a permission to delete messages.
Commands
- /wiki check — check if bot is installed correctly.
- /wiki reload_admins — ask bot to reload admin IDs for current chat. Admins list is collected once and cached. Use this command to update cached data.
- /wiki config — see bot configuration for current chat
- /wiki setmsg TEXTID — use this command in reply to message you want to remember as TEXTID. Here TEXTID could be any alphanumeric token like «rules», «faq», «text44». Example of command: /wiki setmsg faq .
- /wiki cron TEXTID TIME — configure posting time(s) for TEXTID text. TIME could be one of two formats. First, it could be «h1» (every hour), «h2» (every two hours), «h3», «h4», «h6» or «h12» Example: /wiki cron TEXTID h4 . Second, it might be list of hour:minutes pairs delimited by comma. Example: /wiki cron TEXTID 12:00,13:05,16:20 .
- /wiki delmsg TEXTID — forget (remove) TEXTID text. Example: /wiki delmsg faq
- /wiki pin TEXTID MODE — enable/disabling pinning message when posting it. MODE must be «yes» or «no». Example: /wiki pin faq yes .
- /wiki preview TEXTID MODE — enable/disable web page preview. MODE must be «yes» or «no». It is enabled by default. Example: /wiki preview faq no
- wiki showmsg TEXTID — immediately send to the chat a message. With this command you can check that robot renders your scheduled message in the right way.
Scheduling Text Posting
Suppose you want to post chat rules each midnight and noon.
FAQ
How to check if bot installed correctly?
First, complete installation instructions. Then type into chat this command: /wiki check . Fix any issues bot talkes about.
Источник: tgdev.io
Футбольный телеграм бот на Python (3/4): Получение внешних данных
В третей части серии статей по написанию телеграм бота на python, мы настроим работу с внешним API. Бот будет запрашивать результаты матчей, преобразовывать в сообщение и выводить пользователю.
Выбор API для результатов матчей
Обычно я использую Rapid API для получения данных, там много бесплатных предложений. Под нашу задачу хорошо подходит Football Pro. Они дают 100 запросов в день, и возможность получить все результаты за раз.
Зарегистрируйтесь на Rapid Api, создайте приложение и оформите подписку на базовый (бесплатный) план. Сервис бесплатный, но для продолжения требуется карта.
Отлично, теперь можно следить за Лигой Чемпионов.
Получение данных с внешнего API
В прошлой части руководства я заложил будущую логику, хранение результатов по трем лигам в одном ключе. Так как у нас всего 10 лиг и нет разницы в запросе по трем лигам или всем сразу лучше результаты по каждой хранить отдельно. Это сэкономит запросы.
Посмотрим в каком виде приходят данные в ответе с помощью интерфейса сервиса. Во вкладке «Endpoints» слева выберем «Fixtures of Today» и нажмем «Test Endpoint». Ответ появится в правом столбце.
Вот эти строки мы будем использовать для каждого матча:
< . «league_id»:998 . «scores»:< . «ht_score»:»0-0″ «ft_score»:»1-1″ . >»time»: < «status»:»FT» «starting_at»:< «time»:»08:00:00″ . >»minute»:90 . «added_time»:NULL . > . «localTeam»: < «data»:< . «name»:»Hadiya Hosaena» . >> «visitorTeam»: < «data»:< . «name»:»Kedus Giorgis» . >> >
Для отправки запросов нужно установить библиотеку requests: pip install requests==2.25.1 .
Напишем функцию, которая делает запрос к API. Иногда в ответ мы будем получать ошибки, нужно быть готовым. Отправим логи об ошибке и вернем ее.
TODO для вас. Настройте отправку сообщения админу, если fetch_results вернула словарь с ключом «error» .
# fonlinebot/app/service.py import requests import logging from config import BOT_LEAGUES, BOT_LEAGUE_FLAGS, MINUTE, SOCCER_API_URL, SOCCER_API_HEADERS, SOCCER_API_PARAMS # . def limit_control(headers): «»»Контроль бесплатного лимита запросов»»» if headers.get(«x-ratelimit-requests-remaining») is None: logging.error(f»Invalid headers response «) if int(headers[‘x-ratelimit-requests-remaining’]) dict: SOCCER_API_PARAMS[‘leagues’] = «,».join(BOT_LEAGUES.keys()) try: resp = requests.get(SOCCER_API_URL, headers=SOCCER_API_HEADERS, params=SOCCER_API_PARAMS) except requests.ConnectionError: logging.error(«ConnectionError») return limit_control(resp.headers) if resp.status_code == 200: return resp.json() else: logging.warning(f»Data retrieval error []. Headers: «) return #.
Для контроля бесплатных запросов я добавил функцию limit_control . Когда останется меньше 6ти запросов, в кеш добавится соответствующая запись. Теперь бот будет проверять наличие этой записи в кеше, прежде чем отправлять запрос.
Проверку разместим в generate_results_answer . Если запись есть, мы вернем предупреждение.
# fonlinebot/app/service.py #. async def generate_results_answer(ids: list) -> str: «»»Функция создaет сообщение для вывода результатов матчей»»» limit = cache.get(«limit_control») if limit is not None: return limit results = await get_last_results(ids) if results == [[]]*len(ids): return msg.no_results elif msg.fetch_error in results: return msg.fetch_error else: text_results = results_to_text(results) return msg.results.format(matches=text_results) #.
А теперь обновите «bot.py» и «dialogs.py».
Я дописал в функцию 2 строки для проверки answer . Если в ответе текст превышения лимита мы показываем предупреждение.
# fonlinebot/app/dialogs.py #. limit_control: str = «Лимит запросов исчерпан. Возвращайтесь завтра.» fetch_error: str = «Ошибка получения данных, попробуйте позже.» #.
Можете добавить такую запись на минуту и убедиться.
cache.setex(«limit_control», 60, msg.limit_control)
На самом деле лимит начисляется каждые 24 часа с момента подписки. Если вы подписались в 13:00, значит это время обновления остатка. В заголовках ответа по ключу x-ratelimit-requests-reset можно получить остаток времени в секундах.
Очистка данных API и сохранение
Теперь напишем функцию которая распарсит ответ для сохранения в кеш.
TODO для вас. Не всегда нужно обновлять матчи. Например, мы в 8 утра получили список и первый матч начнется в 19.00. До начала первого матча результаты не изменятся, здесь можно сэкономить запросы.
# fonlinebot/app/service.py #. async def parse_matches() -> dict: «»»Функция сбора матчей по API»»» data = <> matches = fetch_results() if matches.get(«error», False): return matches for m in matches[‘data’]: if not data.get(str(m[‘league_id’]), False): data[str(m[‘league_id’])] = [m] else: data[str(m[‘league_id’])].append(m) return data #.
Эту функцию мы вызываем в get_last_results , если не нашли результатов в кеше. Давайте туда допишем сохранение последних результатов:
# fonlinebot/app/service.py #. async def save_results(matches: dict): «»»Сохранение результатов матчей»»» for lg_id in BOT_LEAGUES.keys(): cache.jset(lg_id, matches.get(lg_id, []), MINUTE) async def get_last_results(league_ids: list) -> list: last_results = [cache.jget(lg_id) for lg_id in league_ids] if None in last_results: all_results = await parse_matches() if all_results.get(«error», False): return [msg.fetch_error] else: await save_results(all_results) last_results = [all_results.get(lg_id, []) for lg_id in league_ids] return last_results #.
Если по какой-то лиге у нас нет записи, мы обращаемся к API и сохраняем результат на 1 минуту.
Запись логов в файл
Появились важные логи, которые помогут исправлять ошибки получения данных. Добавим настройки логирования: формат и запись в файл.
# fonlinebot/config.py #. formatter = ‘[%(asctime)s] %(levelname)8s — %(message)s (%(filename)s:%(lineno)s)’ logging.basicConfig( # TODO раскомментировать на сервере # filename=f’bot-from-.log’, # filemode=’w’, format=formatter, datefmt=’%Y-%m-%d %H:%M:%S’, # TODO logging.WARNING level=logging.DEBUG ) #.
Теперь строка будет выглядеть так. Появилось время и место лога:
[2021-02-05 11:38:29] INFO — Database connection established (database.py:38)
Для настройки логирования много вариантов, мы не будет подробно на этом останавливать. Уроки посвящены телеграм боту.
Красивый вывод сообщения пользователю
Хорошо, мы получили список словарей с множеством данных. Его нужно превратить в текст формата:
Английская Премьер-лига Окончен Тоттенхэм 0:1 (0:1) Челси
Форматирование реализуем в results_to_text .
# fonlinebot/app/service.py #. def add_text_time(time: dict) -> str: «»»Подбор текста в зависимости от статуса матча Все статусы здесь: https://sportmonks.com/docs/football/2.0/getting-started/a/response-codes/85#definitions «»» scheduled = [«NS»] ended = [«FT», «AET», «FT_PEN»] live = [«LIVE», «HT», «ET», «PEN_LIVE»] if time[‘status’] in scheduled and time[‘starting_at’][‘time’] is not None: # обрезаем секунды return time[‘starting_at’][‘time’][:-3] elif time[‘status’] in ended: return «Окончен» elif time[‘status’] in live and time[‘minute’] is not None: if time[‘extra_minute’] is not None: return time[‘minute’] + time[‘extra_minute’] return time[‘minute’] else: # для других статусов возвращаем заглушку return «—:—» def results_to_text(matches: list) -> str: «»» Функция генерации сообщения с матчами Получает list[list[dict]]] Возвращает текст: | Английская Премьер-лига | | Окончен Тоттенхэм 0:1 (0:1) Челси | . «»» text = «» for lg_matches in matches: if not lg_matches: continue lg_flag = BOT_LEAGUE_FLAGS[str(lg_matches[0][‘league_id’])] lg_name = BOT_LEAGUES[str(lg_matches[0][‘league_id’])] text += f» n» for m in lg_matches: text += f»7> » if m[‘localteam_id’] == m[‘winner_team_id’]: text += f»** » else: text += f» » if m[‘time’][‘minute’] is not None: text += f»- » else: text += «— » if m[‘scores’][‘ht_score’] is not None: text += f»() » if m[‘visitorteam_id’] == m[‘winner_team_id’]: text += f»**n» else: text += f»n» text += «n» return text #.
Функция циклом проходит по лигам и матчам, формирует читаемый вывод. Перед запуском нужно добавить параметр parse_mode в сообщения, для выделения жирным команд-победителей.
# fonlinebot/app/bot.py #. async def get_results(message: types.Message): #. await message.answer(answer, reply_markup=s.results_kb(user_leagues), parse_mode=types.ParseMode.MARKDOWN) # . async def update_results(callback_query: types.CallbackQuery): # . await bot.edit_message_text( answer, callback_query.from_user.id, message_id=int(cache.get(f»last_msg_»)), parse_mode=types.ParseMode.MARKDOWN, reply_markup=s.results_kb(user_leagues) )
Запустим и проверим, как работает бот:
TODO для вас.
1. Получение данных может длится несколько секунд, добавьте chat_action . Это текст, который отображается сверху во время выполнения кода.
2. Не всегда обновление результатов меняет сообщение, это приводит к ошибке. Пусть сообщение не редактируется, если текст дублирует старый.
Теперь допишем немного тестов и пойдем деплоить.
Тестирование бота
Будем проверять работоспособность API и контроль лимита.
Источник: pythonru.com