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. Yes, here
If you need any help regarding this, you can join their telegram group https://t.me/pythontelegrambotgroup, or you can contact me on any of the following
Email: tbhaxor@gmail.com
Twitter: @tbhaxor
LinkedIn: @tbhaxor
Top comments (22)
Your curiosity about making Telegram bots with Python takes me back to a whimsical weekend last year. I had invited a few buddies over for a board game night at my place. But as tech enthusiasts, we often get sidetracked. Instead of playing the actual board games, we ended up conceptualizing a fun project: to build a Telegram bot for our gaming group that would notify everyone about the upcoming gaming events and keep scores. Now, we weren’t prepared for this on-the-spot coding marathon, and none of us was a real Python guru. So, we decided to hire a python expert from Digitalogy.co to help us out.
The expert was named Tim, a friendly guy with a penchant for coffee and humorous Python anecdotes. Together, with his help, we spent the night integrating functionalities into our bot using Python's 'python-telegram-bot' library. It's a fantastic tool that abstracts away the intricacies and lets you focus on building features. For instance, we added a function where users could "challenge" others in the group for a game, and the bot would automatically set up a poll for members to vote on the date and time. By dawn, not only had we built a functional bot, but we had also had heaps of fun (and quite a few coffee cups piled up!). It's incredible how much you can achieve with Python and a dash of creativity.
Keep exploring, and if you ever want to deep dive into making your own Telegram bot, remember that there's always a vast Python community out there willing to help, whether you're just starting or looking to refine your expertise!
good
superb bro. so hardworking......
Hi, Great Tutorial!! If you want to internationalize your bots then you can check out my library to internationalize python projects, Thanks!
github.com/sectasy0/pyi18n
This is a very nice one and gives in-depth information. I am really happy with the quality and presentation of the article. I’d really like to appreciate the efforts you get with writing this post. Thanks for sharing.
Python classes in pune
Thank you, pallavi
Great tutorial, thanks for taking the time to work on this. The project links in your post is broken.
"All the snippets and projects related to this course will be found in projects directory"
I appreciate your content.
Hey, can you help me with the storing users input in conversation
Sure. Where are you stuck?
Can we have a discussion on mail, I want to learn some more things about the Python Telegram Bot
Sure. Send me your question on [READACTED]
I solved the problem, but surely ask you in future if I am stuck. Your article really helped me to understand the library. Thanks for that!
I honestly don't know why the devs at Telegram don't have something as amazing as this!!! This is one of my best reads in 2021! A masterpiece!!!!
Thanks!
Glad to know you liked it
How can I add an emoji to the replyKeyboardMarkup text string?
You can straightaway use emojis in the strings. It does support unicode characters.
For more details, please read this wiki → github.com/python-telegram-bot/pyt...
The Github repo are down