Документация к ptbot

ptbot — модуль для создания Telegram-ботов. Он умеет отправлять сообщения, редактировать ранее отправленные и реагировать на входящие сообщения от пользователя.

Основан на библиотеке python-telegram-bot, но это урезанная версия для того чтобы начать писать ботов не вникая в сложные концепции. Хорошо подойдёт для начала.

Как начать пользоваться?

Установите библиотеки

Вам понадобится библиотека python-telegram-bot. Установите её в Repl или на своё компьютер, смотря где вы программируете.

Скачайте код

Создайте файл с названием ptbot.py и положите рядом со своей программой.

Затем скопируйте в него этот код.

Создайте бота

Для запуска библиотеки нужно достать пару ключей доступа.

Прежде всего вам нужен API ключ от Telegram-бота. Его можно получить у Отца ботов. Введите команду /newbot в чате с ним и следуйте инструкциям.

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

Узнайте свой `id` в Telegram

Его вам скажет Бот-справочник. Он нужен чтобы подсказать боту как вас найти.

Отправьте первое сообщение

Скопируйте код и поменяйте значения TOKEN и CHAT_ID, запустите программу.

import ptbot

TG_TOKEN = '958423683:AAEAtJ5Lde5YYfu8GldVhSGCAsxAYbzUIYg'  # подставьте свой ключ API
TG_CHAT_ID = '228593533'  # подставьте свой ID
bot = ptbot.Bot(TG_TOKEN)
bot.send_message(TG_CHAT_ID, "Бот запущен")

От бота в Telegram придёт сообщение:

Что умеет библиотека

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

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

Вот как можно отправить пользователю сообщение с текстом “Моё сообщение”:

import ptbot

bot = ptbot.Bot("Мой токен")  # подставьте свой ключ API
bot.send_message("Мой id чата", "Моё сообщение")

Не забудьте заменить Мой токен и Мой id чата на свои, подробнее см. Отправьте первое сообщение.

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

Метод send_message возвращает id сообщения, только что отправленного пользователю. Зная id сообщения вы можете его редактировать. Как получить id :

message_id = bot.send_message("Мой id чата", "Моё сообщение")
print('ID сообщения', message_id)

И вот как редактировать:

bot.update_message("Мой id чата", message_id, "Новое сообщение")

Запуск бота

Метод run_bot нужен для трёх других методов:

Создание таймера
Создание периодического таймера
Ожидание сообщения пользователя

Метод run_bot ничего не возвращает. Он никогда не завершает своей работы. Метод вводит программу в “режим ожидания сообщений” и может работать вечно:

bot = ptbot.Bot("Мой токен")
bot.run_bot()

print("Эта строка кода никогда не запустится")

Последняя строчка кода никогда не выведет на экран сообщение из-за этого “режима ожидания”.

Всегда вызывайте run_bot в конце своей программы.

Создание таймера

Метод create_timer() создаёт таймер, на несколько секунд. Этот метод не работает без метода run_bot.

Метод требует два аргумента:

Сколько секунд ждать
Функция-коллбэк, которая запустится через это количество секунд.

Самый простой вариант использования:

import ptbot

def notify():
    print("Функция запустилась, но через 5 секунд!")

bot = ptbot.Bot("Мой токен")
bot.create_timer(5, notify)

bot.run_bot()

Когда вы запустите этот код, создастся таймер. Он подождёт 5 секунд и после этого запустит функцию notify: в консоль выведется “Функция запустилась!”.

Создание периодического таймера

Метод create_countdown() ведёт обратный отсчёт, каждую секунду запуская функцию-коллбэк. Этот метод не работает без метода run_bot.

Метод требует 2 аргумента:

Сколько секунд повторять задачу
Функция-коллбэк, которая будет запускаться каждую секунду, пока не выйдет время.

Функция-коллбэк должна принимать позиционный аргумент secs_left. В него передается число с количеством секунд, что осталось до конца отсчёта.

Пример:

import ptbot

def notify_progress(secs_left):
    print("Осталось секунд:", secs_left)

bot = ptbot.Bot("Мой токен")
bot.create_countdown(5, notify_progress)

bot.run_bot()

Этот код каждую секунду будет печатать Осталось секунд: 5 в течение 5 секунд:

Ожидание сообщения пользователя

Метод reply_on_message() умеет отвечать на сообщения пользователей. Этот метод не работает без метода run_bot.

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

Благодаря chat_id вы можете писать сообщения не только себе, но и любому другому человеку, который напишет боту.

Пример:

import ptbot

def reply(chat_id, text):
    print("Привет! Пользователь с ID {} написал мне: {}".format(chat_id, text))

bot = ptbot.Bot("Мой токен")
bot.reply_on_message(reply)

bot.run_bot()

Если пользователь напишет боту Ты ждешь? , то тот выведет в треминал Привет! Ты написал мне: Ты ждешь?.

Внутри функции def reply(text): можно свободно дописывать любой код. Название у функции тоже можно менять. Вот несколько примеров:

def log_all_messages(chat_id, text):
    print("Получил сообщение от пользователя {}: {}".format(chat_id, text))

bot = ptbot.Bot("Мой токен")
bot.reply_on_message(log_all_messages)

bot.run_bot()

def say_hello(chat_id, text):
    message_id = bot.send_message(chat_id, "Привет! Я здесь, я работаю!")
    print('Я отправил сообщение #', message_id)

bot = ptbot.Bot("Мой токен")
bot.reply_on_message(say_hello)

bot.run_bot()

Общение между методами

Методы могут передавать данные между собой. Например, вы хотите вывести сообщение пользователя в функции notify:

import ptbot

def reply(chat_id, text):
    bot.create_timer(5, notify)


def notify():
    bot.send_message(chat_id, "Прошло 5 секунд!")

bot = ptbot.Bot(TOKEN)
bot.reply_on_message(reply)
bot.run_bot()

Этот код выдаст ошибку, т.к. функция notify не может “украсть” переменную chat_id у функции reply. Но в ptbot есть решение для такого:

import ptbot

def reply(chat_id, text):
    bot.create_timer(5, notify, chat_id=chat_id)


def notify(chat_id):
    bot.send_message(chat_id, "Прошло 5 секунд!")

bot = ptbot.Bot(TOKEN)
bot.reply_on_message(reply)
bot.run_bot()

Изменения произошли в двух местах:

Функция notify теперь требует аргумент chat_id:
```
def notify(chat_id):
```
Функция create_timer передаёт этот аргумент:
```
bot.create_timer(5, notify, chat_id=chat_id)
```

Так же может делать и другой метод, create_countdown:

import ptbot

def reply(chat_id, text):
    bot.create_countdown(5, notify, chat_id=chat_id)


def notify(secs_left, chat_id):
    bot.send_message(chat_id, "Осталось {} секунд!".format(secs_left))

bot = ptbot.Bot(TOKEN)
bot.reply_on_message(reply)
bot.run_bot()