Skip to main content

Python Telegram bot api.

Project description

A Python implementation for the Telegram Bot API.


Build Status

How to install

Python 2 or Python 3 is required.

  • Install from source

$ git clone
$ cd pyTelegramBotAPI
$ python install
  • or install with pip

$ pip install pyTelegramBotAPI


  • Sending a message.

import telebot

TOKEN = '<token string>'

tb = telebot.TeleBot(TOKEN)
# tb.send_message(chatid, message)
tb.send_message(281281, 'gogo power ranger')
  • Echo Bot

import telebot
import time

TOKEN = '<token_string>'

def listener(messages):
    When new messages arrive TeleBot will call this function.
    for m in messages:
        chatid =
        if m.content_type == 'text':
            text = m.text
            tb.send_message(chatid, text)

tb = telebot.TeleBot(TOKEN)
tb.set_update_listener(listener) #register listener
#Use none_stop flag let polling will not stop when get new message occur error.
# Interval setup. Sleep 3 secs between request new message.

while True: # Don't let the main Thread end.

TeleBot API usage

import telebot
import time

TOKEN = '<token_string>'
tb = telebot.TeleBot(TOKEN) #create a new Telegram Bot object

# TeleBot will not create thread for message listener. Default is True.
tb = telebot.TeleBot(TOKEN, False)

# 4 Thread worker for message listener.
tb = telebot.TeleBot(TOKEN, True, 4)

# Setup telebot handler to telebot logger. If you want to get some information from telebot.
# More information at Logging section
handler = logging.StreamHandler(sys.stdout)

# getMe
user = tb.get_me()

# sendMessage
tb.send_message(chatid, text)

# forwardMessage
# tb.forward_message(10894,926,3)
tb.forward_message(to_chat_id, from_chat_id, message_id)

# sendPhoto
photo = open('/tmp/photo.png', 'rb')
tb.send_photo(chat_id, photo)
file_id = 'AAAaaaZZZzzz'
tb.send_photo(chat_id, file_id)

# sendAudio
audio = open('/tmp/audio.ogg', 'rb')
tb.send_audio(chat_id, audio)
file_id = 'AAAaaaZZZzzz'
tb.send_audio(chat_id, file_id)

# sendDocument
doc = open('/tmp/file.txt', 'rb')
tb.send_document(chat_id, doc)
file_id = 'AAAaaaZZZzzz'
tb.send_document(chat_id, file_id)

# sendSticker
sti = open('/tmp/sti.webp', 'rb')
tb.send_sticker(chat_id, sti)
file_id = 'AAAaaaZZZzzz'
tb.send_sticker(chat_id, file_id)

# sendVideo
video = open('/tmp/video.mp4', 'rb')
tb.send_video(chat_id, video)
file_id = 'AAAaaaZZZzzz'
tb.send_video(chat_id, file_id)

# sendLocation
tb.send_location(chat_id, lat, lon)

# sendChatAction
# action_string can be one of the following strings: 'typing', 'upload_photo', 'record_video', 'upload_video',
# 'record_audio', 'upload_audio', 'upload_document' or 'find_location'.
tb.send_chat_action(chat_id, action_string)

# Use the ReplyKeyboardMarkup class.
# Thanks pevdh.
from telebot import types

markup = types.ReplyKeyboardMarkup()
markup.add('a', 'v', 'd')
tb.send_message(chat_id, message, reply_markup=markup)

# or add strings one row at a time:
markup = types.ReplyKeyboardMarkup()
markup.row('a', 'v')
markup.row('c', 'd', 'e')
tb.send_message(chat_id, message, reply_markup=markup)

Creating a Telegram bot with the pyTelegramBotAPI

There are two ways to define a Telegram Bot with the pyTelegramBotAPI. ### The listener mechanism

  • First, create a TeleBot instance.

import telebot

TOKEN = '<token string>'

bot = telebot.TeleBot(TOKEN)
  • Then, define a listener function.

def echo_messages(*messages):
    Echoes all incoming messages of content_type 'text'.
    for m in messages:
        chatid =
        if m.content_type == 'text':
            text = m.text
            bot.send_message(chatid, text)
  • Now, register your listener with the TeleBot instance and call TeleBot#polling()


while True: # Don't let the main Thread end.
  • use Message’s content_type attribute to check the type of Message. Now Message supports content types:

  • text

  • audio

  • document

  • photo

  • sticker

  • video

  • location

  • contact

  • new_chat_participant

  • left_chat_participant

  • new_chat_title

  • new_chat_photo

  • delete_chat_photo

  • group_chat_created

  • That’s it!

The decorator mechanism

  • First, create a TeleBot instance.

import telebot

TOKEN = '<token string>'

bot = telebot.TeleBot(TOKEN)
  • Next, define all of your so-called message handlers and decorate them with @bot.message_handler

# Handle /start and /help
@bot.message_handler(commands=['start', 'help'])
def command_help(message):
    bot.reply_to(message, "Hello, did someone call for help?")

# Handles all messages which text matches the regex regexp.
# See
# This regex matches all sent url's.
def command_url(message):
    bot.reply_to(message, "I shouldn't open that url, should I?")

# Handle all sent documents of type 'text/plain'.
@bot.message_handler(func=lambda message: message.document.mime_type == 'text/plain', content_types=['document'])
def command_handle_document(message):
    bot.reply_to(message, "Document received, sir!")

# Default command handler. A lambda expression which always returns True is used for this purpose.
@bot.message_handler(func=lambda message: True, content_types=['audio', 'video', 'document', 'text', 'location', 'contact', 'sticker'])
def default_command(message):
    bot.reply_to(message, "This is the default command handler.")
  • And finally, call bot.polling()


while True: # Don't end the main thread.

Use whichever mechanism fits your purpose! It is even possible to mix and match.


Now you can use Telebot module logger to log some information in Telebot. Use telebot.logger to get Telebot module logger.

logger = telebot.logger
formatter = logging.Formatter('[%(asctime)s] %(thread)d {%(pathname)s:%(lineno)d} %(levelname)s - %(message)s',
                                  '%m-%d %H:%M:%S')
ch = logging.StreamHandler(sys.stdout)
logger.setLevel(logging.DEBUG)  # or use logging.INFO

Telegram Chat Group

Get help. Discuss. Chat.

Join pyTelegramBotAPI Chat Group.


Project details

Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyTelegramBotAPI-0.3.0.tar.gz (9.5 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page