pyTelegramBotAPI

A Python implementation for the Telegram Bot API.

See https://core.telegram.org/bots/api

How to install

Python 2 or Python 3 is required.

Install from source

$ git clone https://github.com/eternnoir/pyTelegramBotAPI.git
$ cd pyTelegramBotAPI
$ python setup.py install

or install with pip

$ pip install pyTelegramBotAPI

Example

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

TOKEN = '<token_string>'


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


tb = telebot.TeleBot(TOKEN)
tb.set_update_listener(listener) #register listener
tb.polling()

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

TeleBot API usage

import telebot
import time

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

# 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)

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

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

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

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

# 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 = m.chat.id
        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()

bot.set_update_listener(echo_messages)
bot.polling()

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

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 https://en.wikipedia.org/wiki/Regular_expression
# This regex matches all sent url's.
@bot.message_handler(regexp='((https?):((//)|(\\\\))+([\w\d:#@%/;$()~_?\+-=\\\.&](#!)?)*)')
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()

bot.polling()

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

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

TODO

getMe
sendMessage
forwardMessage
sendPhoto
sendAudio
sendDocument
sendSticker
sendVideo
sendLocation
sendChatAction
getUserProfilePhotos
getUpdate

5.3 KiB Raw Blame History