Course Outline
Prerequisite Knowledge and Requirements
Basic python knowledge
Telegram Account
About Course
In this course, you will start creating a bot from scratch, discovering all possible settings to utilize all power of Bot API and creating a real-world application. All this by using Python and Telegram Bot
Codes / Projects
All the snippets and projects related to this course will be found in projects directory
NOTE : If you will be making any educational project regarding this course, I would like to encourage you to send a PR regarding the same, here
What are Bots
Simple telegram accounts operated by an application
Not actually designed for chatting
Can be used to simplify the task
Teach
Play
Search
Broadcast
Remind
Connect
Users can interact with them via
Message
Emoticons
Commands
Inline requests
Setting up Telegram Bot
Open telegram and search for BotFather
Send /start command to start and associate the account with yours
Send /help command to show the help
Send /newbot command and follow the instruction
Send /mybots command to list your bot, select the desired bot
Click on API Token
Understanding Other Bot Settings
Send /mybots command to list your bot, select the desired bot
Click on "Bot Settings" and you will see various options.
Click on "Inline Mode". If you want the bot to accept inline messages beyond the commands.
Now you can click on Back to Bot button and click on Edit Bot button. Here you can customize your bots like setting a bot description (what it does, what it is used for etc), setting a bot about and profile picture.
NOTE: While changing the profile picture, botfather expects you to upload a valid image file.
Limitation of the Bot
Only user can initiate the chat
The download limit is 20MB and upload limit is 50MB only
Send messages limit is capped up to 30 msg per second. However, you can ask @botsupport to increase it.
With this limitation, comes another power, bots can edit own messages and another's messages in the channel where the bot has admin rights
Getting messages from Telegram
There are two ways to get user messages from telegram.
Polling
It's a way of asking Telegram every X seconds whether any new message has come, and receive messages or asks later from telegram.
Web Hooks
It's a way in which telegram sends all updates to the URL that has been configured to accept messages as soon as the user sends new messages.
HTTP Interface of Bots API
Documentation: https://core.telegram.org/bots/api
Available Method: https://core.telegram.org/bots/api#available-methods
Base URL: https://api.telegram.org/bot[BOT_API_KEY]/[methodName]
Getting bot description
Method Name: getMe
In my case,
{
"ok": true,
"result": {
"id": 920296790,
"is_bot": true,
"first_name": "TELE BOT",
"username": "tel_ebot",
"can_join_groups": true,
"can_read_all_group_messages": false,
"supports_inline_queries": false
}
}
Getting new messages
Available Methods: https://core.telegram.org/bots/api#getting-updates
Method Name: getUpdates
In my case
{
"ok": true,
"result": [
{
"update_id": 643663200,
"message": {
"message_id": 3,
"from": {
"id": 517852228,
"is_bot": false,
"first_name": "Gurkirat",
"last_name": "Singh",
"username": "username_of_the_sender",
"language_code": "en"
},
"chat": {
"id": 517852228,
"first_name": "Gurkirat",
"last_name": "Singh",
"username": "username_of_the_sender",
"type": "private"
},
"date": 1586779436,
"text": "hello"
}
}
]
}
More methods on Get Updates: https://core.telegram.org/bots/api#getting-updates
Sending Messages to the User
Method Name: sendMessage
In this, you will see me creating an echo bot that will be listening to all the messages sent by the user. I will then read the last message (-1 index in the python list) and send the same message with the format "You send me "{MESSAGE_TEXT}"" message.
The code is self-explanatory, and I have added some comments. However, if you couldn't get anything, leave a comment
import urllib.request as request
from urllib.error import HTTPError
from http.client import HTTPResponse
from typing import Dict, List, Union
import json
from datetime import datetime
import signal
import os
signal.signal(signal.SIGINT, signal.SIG_DFL)
class TelegramEcho:
def init(self, TG_KEY: str):
self.TG_URL = "https://api.telegram.org/bot{key}/{method}"
self.TG_KEY = TG_KEY
self.__last = None
self.__last_time = None
pass
def run(self):
"""
method to handle the incoming message and the send echo message to the user
"""
while True:
try:
# getting the incoming data
incoming = self.__handle_incoming()
# checking if incoming message_id is same as of last, then skip
if self.__last == incoming["message"]["message_id"]:
continue
else:
self.__last = incoming["message"]["message_id"]
# adding more validation to prevent messaging the last message whenever the polling starts
if not self.__last_time:
self.__last_time = incoming["message"]["date"]
continue
elif self.__last_time < incoming["message"]["date"]:
self.__last_time = incoming["message"]["date"]
else:
continue
# finally printing the incoming message
self.__print_incoming(incoming)
# now sending the echo message
outgoing = self.__handle_outgoing(
incoming["message"]["chat"]["id"],
incoming["message"]["text"])
# finally printing the outgoing message
self.__print_outgoing(outgoing)
pass
except (HTTPError, IndexError):
continue
pass
pass
def __handle_incoming(self) -> Dict[str, Union[int, str]]:
"""
method fetch the recent messages
"""
# getting all messages
getUpdates = request.urlopen(
self.TG_URL.format(key=self.TG_KEY, method="getUpdates"))
# parsing results
results: List[Dict[str, Union[int, str]]] = json.loads(
getUpdates.read().decode())["result"]
# getting the last error
return results[-1]
def __print_incoming(self, incoming: Dict[str, Union[int, str]]):
"""
method to print the incoming message on console
"""
print("[<<<] Message Recieved on %s" % datetime.fromtimestamp(
incoming["message"]["date"]).strftime("%Y-%m-%d %H:%M:%S"))
print("\tText: %s" % incoming["message"]["text"])
print("\tFrom: %s" %
incoming["message"]["from"].get("first_name", "") + " " +
incoming["message"]["from"].get("last_name", ""))
print("\tMessage ID: %d" % incoming["message"]["message_id"])
print("-" * os.get_terminal_size().columns)
pass
def __handle_outgoing(self, chat_id: int,
message_txt: str) -> Dict[str, Union[int, str]]:
"""
method to send the echo message to the same chat
"""
# making the post data
_data: Dict[str, Union[int, str]] = {
"chat_id":
chat_id,
"text":
"You sent me \"{MESSAGE_TEXT}\"".format(MESSAGE_TEXT=message_txt)
}
# creating the request
_request: request.Request = request.Request(
self.TG_URL.format(key=self.TG_KEY, method="sendMessage"),
data=json.dumps(_data).encode('utf8'),
headers={"Content-Type": "application/json"})
# sending HTTP request, for sending message to the user
sendMessage: HTTPResponse = request.urlopen(_request)
result: Dict[str, Union[int, str]] = json.loads(
sendMessage.read().decode())["result"]
return result
def __print_outgoing(self, outgoing):
"""
method to print outgoing data on the console
"""
print("[>>>] Message Send on %s" % datetime.fromtimestamp(
outgoing["date"]).strftime("%Y-%m-%d %H:%M:%S"))
print("\tText: %s" % outgoing["text"])
print("\tFrom: %s" % outgoing["from"]["first_name"])
print("\tMessage ID: %d" % outgoing["message_id"])
print("-" * os.get_terminal_size().columns)
pass
pass
if name == "main":
tg = TelegramEcho("YOUR API KEY")
tg.run()
Make sure you add the API Key before running this code. After running the above code, you will get the output like below,
Telegram Bot Libraries
As you have seen, telegram provides a plethora of methods and APIs to handle the bot through any language, the open-source community has developed a python client using these API under the hood to increase developer's productivity.
The one I will be using is python-telegram-bot. While making this course, it has approx. 10k stars, 38 open issues and last commit was made 2 days ago
Installing the Module
via pip
pip install -U python-telegram-bot
via conda
conda install -c conda-forge python-telegram-bot
Glance of the Usage
In this I will be implementing get_me method, returning the bot details
from telegram import Bot
initializing the bot with API
bot = Bot("API KEY")
getting the bot details
print(bot.get_me())
How fascinating, the developers encapsulated all the backend, letting other developers write neat and clone. It not only provides neat code but also makes payment processing, handlers, and other more features even beyond sending HTTP Requests
The complete documentation of python-telegram-bot: https://python-telegram-bot.readthedocs.io/en/stable/
Using Handlers on Commands
I hope you would have created some commands, now let's make the bot handle those
The library python-telegram-bot provides various Handlers from which I will be using CommandHandler
from telegram.ext.commandhandler import CommandHandler
from telegram.ext.updater import Updater
from telegram.ext.dispatcher import Dispatcher
from telegram.update import Update
from telegram.ext.callbackcontext import CallbackContext
from telegram.bot import Bot
initializing an updator
documentation: https://python-telegram-bot.readthedocs.io/en/latest/telegram.ext.updater.html#telegram.ext.Updater
updater = Updater("API KEY",
use_context=True)
getting the dispatcher required to handle the command /start and send message back to the user
documentation: https://python-telegram-bot.readthedocs.io/en/latest/telegram.ext.dispatcher.html#telegram.ext.Dispatcher
dispatcher: Dispatcher = updater.dispatcher
def start(update: Update, context: CallbackContext):
"""
the callback for handling start command
"""
# getting the bot from context
# documentation: https://python-telegram-bot.readthedocs.io/en/latest/telegram.bot.html#telegram-bot
bot: Bot = context.bot
# sending message to the chat from where it has received the message
# documentation: https://python-telegram-bot.readthedocs.io/en/latest/telegram.bot.html#telegram.Bot.send_message
bot.send_message(chat_id=update.effective_chat.id,
text="You have just entered start command")
register a handler (here command handler)
documentation: https://python-telegram-bot.readthedocs.io/en/latest/telegram.ext.dispatcher.html#telegram.ext.Dispatcher.add_handler
dispatcher.add_handler(
# it can accept all the telegram.ext.Handler, CommandHandler inherits Handler class
# documentation: https://python-telegram-bot.readthedocs.io/en/latest/telegram.ext.commandhandler.html#telegram-ext-commandhandler
CommandHandler("start", start))
starting polling updates from Telegram
documentation: https://python-telegram-bot.readthedocs.io/en/latest/telegram.ext.updater.html#telegram.ext.Updater.start_polling
updater.start_polling()
Posting HTML Message
In this I will show how to send an HTML formatted message to the user. I will be using telegram.ParseMode.HTML parser for with send_message method.
Updating just one send_message line in above code
from telegram.ext.commandhandler import CommandHandler
from telegram.ext.updater import Updater
from telegram.ext.dispatcher import Dispatcher
from telegram.update import Update
from telegram.ext.callbackcontext import CallbackContext
from telegram.bot import Bot
from telegram.parsemode import ParseMode
updater = Updater("API KEY",
use_context=True)
dispatcher: Dispatcher = updater.dispatcher
def start(update: Update, context: CallbackContext):
"""
the callback for handling start command
"""
bot: Bot = context.bot
# Added HTML Parser to the existing command handler
# documentation: https://python-telegram-bot.readthedocs.io/en/stable/telegram.parsemode.html#telegram.ParseMode.HTML
bot.send_message(
chat_id=update.effective_chat.id,
text=
"Hello User, You have used <b>start</b> command. Search about developer on google, <a href='https://www.google.com/search?q=tbhaxor'>@tbhaxor</a>",
parse_mode=ParseMode.HTML,
)
dispatcher.add_handler(CommandHandler("start", start))
updater.start_polling()
The message user will receive will be the rendered HTML you have passed in text argument
Using Keyboards to Build Menus
In this, you will embrace the power of another tool provided by telegram, Keyboard. Telegram has two types plain keyboard and inline, the first is attached to the group or chat. The second one is attached to the message
Simple Keyboard
In this, I will be using telegram.ReplyKeyboardMarkup to add new keyboard to the chat and telegram.ReplyKeyboardRemove to remove the keyboard from the chat
from telegram.ext.updater import Updater
from telegram.update import Update
from telegram.ext.callbackcontext import CallbackContext
from telegram.ext.commandhandler import CommandHandler
from telegram.replykeyboardmarkup import ReplyKeyboardMarkup
from telegram.replykeyboardremove import ReplyKeyboardRemove
from telegram.ext.messagehandler import MessageHandler
from telegram.ext.filters import Filters
updater = Updater("API KEY", use_context=True)
def start(update: Update, context: CallbackContext):
"""
method to handle the /start command and create keyboard
"""
# defining the keyboard layout
kbd_layout = [['Option 1', 'Option 2'], ['Option 3', 'Option 4'],
["Option 5"]]
# converting layout to markup
# documentation: https://python-telegram-bot.readthedocs.io/en/stable/telegram.replykeyboardmarkup.html
kbd = ReplyKeyboardMarkup(kbd_layout)
# sending the reply so as to activate the keyboard
update.message.reply_text(text="Select Options", reply_markup=kbd)
def remove(update: Update, context: CallbackContext):
"""
method to handle /remove command to remove the keyboard and return back to text reply
"""
# making a reply markup to remove keyboard
# documentation: https://python-telegram-bot.readthedocs.io/en/stable/telegram.replykeyboardremove.html
reply_markup = ReplyKeyboardRemove()
# sending the reply so as to remove the keyboard
update.message.reply_text(text="I'm back.", reply_markup=reply_markup)
pass
def echo(update: Update, context: CallbackContext):
"""
message to handle any "Option [0-9]" Regrex.
"""
# sending the reply message with the selected option
update.message.reply_text("You just clicked on '%s'" % update.message.text)
pass
updater.dispatcher.add_handler(CommandHandler("start", start))
updater.dispatcher.add_handler(CommandHandler("remove", remove))
adding the message handler with filter to handle the Option [0-9] regex input
documentation for MessageHandler: https://python-telegram-bot.readthedocs.io/en/stable/telegram.ext.messagehandler.html
documentation for Filter: https://python-telegram-bot.readthedocs.io/en/stable/telegram.ext.filters.html#telegram.ext.filters.Filters
updater.dispatcher.add_handler(MessageHandler(Filters.regex(r"Option [0-9]"), echo))
updater.start_polling()
Inline Keyboard
In this I will be using telegram.ext.CallbackQueryHandler which returns a telegram.CallbackQuery when user presses an telegram.InlineKeyboardButton
from telegram import InlineKeyboardButton, InlineKeyboardMarkup
from telegram.ext.updater import Updater
from telegram.ext.commandhandler import CommandHandler
from telegram.ext.callbackqueryhandler import CallbackQueryHandler
from telegram.callbackquery import CallbackQuery
from telegram.ext.callbackcontext import CallbackContext
from telegram.update import Update
from telegram.message import Message
import sys
creating updater
updater: Updater = Updater("API KEY",
use_context=True)
def error(update: Update, context: CallbackContext):
"""Log Errors caused by Updates."""
sys.stderr.write("ERROR: '%s' caused by '%s'" % context.error, update)
pass
def start(update: Update, context: CallbackContext):
"""
callback method handling /start command
"""
# creating list of input buttons
# documentation: https://python-telegram-bot.readthedocs.io/en/stable/telegram.inlinekeyboardbutton.html
keyboard = [[
InlineKeyboardButton("Option 1", callback_data='1'),
InlineKeyboardButton("Option 2", callback_data='2')
], [InlineKeyboardButton("Option 3", callback_data='3')]]
# creating a reply markup of inline keyboard options
# documentation: https://python-telegram-bot.readthedocs.io/en/stable/telegram.inlinekeyboardmarkup.html
reply_markup = InlineKeyboardMarkup(keyboard)
# sending the message to the current chat id
# documentation: https://python-telegram-bot.readthedocs.io/en/stable/telegram.message.html#telegram.Message.reply_text
update.message.reply_text('Please choose:', reply_markup=reply_markup)
pass
def button(update, context):
"""
callback method handling button press
"""
# getting the callback query
# documentation: https://python-telegram-bot.readthedocs.io/en/stable/telegram.callbackquery.html
query: CallbackQuery = update.callback_query
# CallbackQueries need to be answered, even if no notification to the user is needed
# Some clients may have trouble otherwise. See https://core.telegram.org/bots/api#callbackquery
# documentation: https://python-telegram-bot.readthedocs.io/en/stable/telegram.callbackquery.html#telegram.CallbackQuery.answer
query.answer()
# editing message sent by the bot
# documentation: https://python-telegram-bot.readthedocs.io/en/stable/telegram.callbackquery.html#telegram.CallbackQuery.edit_message_text
query.edit_message_text(text="Selected option: {}".format(query.data))
adding listeners
updater.dispatcher.add_handler(CommandHandler('start', start)) # handling /start command
updater.dispatcher.add_handler(CallbackQueryHandler(button)) # handling inline buttons pressing
updater.dispatcher.add_error_handler(error) # error handling
started polling
updater.start_polling()
Sending Force Replies
Upon recieving messages from user, telegram bot will display a reply interface to the user like if user has selected the bot message to reply back. This could be used in creating step-by-step user friendly interface.
I will be using telegram.ForceReply to send force reply
from telegram.forcereply import ForceReply
from telegram.ext.filters import Filters
from telegram.ext.updater import Updater
from telegram.ext.messagehandler import MessageHandler
from telegram.ext.callbackcontext import CallbackContext
from telegram.update import Update
updater = Updater("API KEY", use_context=True)
def echo(update: Update, context: CallbackContext):
# sending the force reply to the user
# documentation: https://python-telegram-bot.readthedocs.io/en/stable/telegram.forcereply.html
update.message.reply_text(reply_markup=ForceReply(selective=True), text="Reply to this message")
pass
updater.dispatcher.add_handler(MessageHandler(Filters.text, echo))
updater.start_polling()
Chat Action
Now suppose you created a bot that processes some files / information that could take some time. The user might think bot is broken and close it. The telegram provides very cool option ChatActions to send user messages immediately after his/her submission.
I will be using telegram.Bot.send_chat_action along with telegram.ChatAction
from telegram.bot import Bot
from telegram.update import Update
from telegram.ext.updater import Updater
from telegram.ext.callbackcontext import CallbackContext
from telegram.ext.messagehandler import MessageHandler
from telegram.ext.filters import Filters
from telegram.chataction import ChatAction
from time import sleep
updater = Updater("API KEY", use_context=True)
def echo(update: Update, context: CallbackContext):
# sending the chat action, under the name of bot it will show Typing...
# documentation: https://python-telegram-bot.readthedocs.io/en/stable/telegram.chataction.html
context.bot.send_chat_action(chat_id=update.effective_chat.id, action=ChatAction.TYPING)
# simulating some long processing
sleep(3)
# sending reply when it's done
update.message.reply_text(text="Hey ya!! You sent me '%s'" % update.message.text)
updater.dispatcher.add_handler(MessageHandler(Filters.text, echo))
updater.start_polling()
Deep Linking
Telegram also supports deeplinking. It helps to create a refereal system to promote your bot or products via bot.
I will be using telegram.utils.helpers.create_deep_linked_url to create a deep link
from telegram.bot import Bot
from telegram.utils.helpers import create_deep_linked_url
from telegram.ext.commandhandler import CommandHandler
from telegram.ext.callbackcontext import CallbackContext
from telegram.update import Update
from telegram.ext.updater import Updater
import re
updater = Updater("API KEY", use_context=True)
def generate(update: Update, context: CallbackContext):
"""
method to create a deep link and send it to the current user for sharing
"""
# generating a sharable link with the payload
# documentation: https://python-telegram-bot.readthedocs.io/en/stable/telegram.utils.helpers.html#telegram.utils.helpers.create_deep_linked_url
url = create_deep_linked_url(context.bot.get_me().username, update.message.chat.username)
update.message.reply_text(text="Share it with your friends: %s.\n Copy the link and share it with them" % url)
pass
def start(update: Update, context: CallbackContext):
"""
method to run on
"""
# extracting the payload with /start
_ = re.findall(r"(?:/start )(.+)", update.message.text)
# checking if it exists and sending message accordingly
if len(_) > 0:
update.message.reply_text(text="You have been refered by: %s" % _[0])
pass
else:
update.message.reply_text(text="Hello, It seems you are new to this bot")
pass
update.message.reply_text(text="Use /generate to create your own referal")
pass
updater.dispatcher.add_handler(CommandHandler("generate", generate))
updater.dispatcher.add_handler(CommandHandler("start", start))
updater.start_polling()
Course Outro
Thanks for reading this course, I would encourage you to explore this wonderful telegram client yourself. I would be happy to see your creations after pursuing this tutorial. In future, if I planned to add more snippets and projects, you know where to find it.
Top comments (0)