Skip to main content

Telegram bot library for Python and humans

Project description

TeBot - Telegram bot library for Python and humans

The goal is to to keep it simple.

Demo (sometimes may not work): @demo_tebot

How to install

pip3 install tebot

How to use

Start bot

If your project uses neotasker

from tebot import TeBot

# interval - polling interval, must be specified
mybot = TeBot(interval=2)
# obtain token from https://telegram.me/BotFather
mybot.set_token('botsecrettoken')
# optionally - load previous state
import json
with open('bot-state.json') as fh:
    mybot.load(json.loads(fh.read()))
# start bot
mybot.start()

If it doesn't:

from neotasker import task_supervisor
from tebot import TeBot

task_supervisor.create_aloop('default', default=True)
task_supervisor.start()
mybot = TeBot(interval=2)
mybot.set_token('botsecrettoken')
mybot.start()

(refer to neotasker documentation for more info)

Stop bot

mybot.stop()
# if your project doesn't use neotasker
task_supervisor.stop()
# optionally - save bot state
with open('bot-state.json', 'w') as fh:
    fh.write(json.dumps(mybot.serialize()))

Send messages

# text
mybot.send(text='hello world', chat_id=chat_id)
# files
with open('image.jpg', 'rb') as fh:
    mybot.send(media=fh.read(), chat_id=chat_id)

If message is being sent from the handler and chat_id is not specified, current chat ID is used:

@mybot.route(path='/start')
def start(**kwargs):
    mybot.send('bot started')

Download files

def somehandler(**kwargs):
    payload = kwargs.get('payload')
    if 'document' in payload:
        content = mybot.get_file_contents(payload['document'].get('file_id'))
        if 'content' is None:
            # unable to download file
        else:
            # process file content

High-level API: routes

TeBot has flask-style routes, which may be registered either by calling

    mybot.register_handler(fn, path, methods)

or with function decorator:

# message handler. can be only one, registered to handle all regular messages
@mybot.route(methods='message')
def my_message(chat_id, text, **kwargs):
    # some code

# command handler for /start and /help
@mybot.route(path=['/start', '/help'])
def start(**kwargs):
    mybot.send('got HELP command')

# command and callback query handler
@mybot.route(methods='*')
def default_cmd_handler(path, **kwargs):
    mybot.send(f'command not implemented: {path}')

Route parameters

  • path command path, can be string or list/tuple for multiple commands

  • methods can be either a string or a list/tuple. Valid values are: "message", "command" (default if no methods specified) and "query" / "callback_query". If "*" specified, the method is registered for both commands and callback queries

Handler kwargs

The following kwargs are sent to registered handlers:

  • text message text (only for message handler)

  • path command path (e.g. "/select" for "/select * from data")

  • query_string command query string (e.g. "* from data" for the above example)

  • chat_id current chat id

  • query_id callback query id, if handler is executed as a callback query handler

  • payload full request payload

  • method "command" or "query" for callback query

Handler return data

  • If command is handled, the handler may return nothing

  • If callback query is handled, the handler may return dict, which is used as a payload for the callback query answer (e.g. include "url", "show_alert" etc, see Telegram Bot API for more details)

Low-level API: handlers

Override class methods:

  • handle_message handle regular messages

  • handle_command handle commands (starting with '/')

  • handle_query handle callback queries

  • on_message override to implement advanced message handling

  • on_query override to implement advanced callback query handling

Bot options

mybot.timeout = 5 # set Telegram API timeout (default: 10 sec)
mybot.retry_interval = 1 # if API command fails, re-send it in 1 second
                         # (default: None, don't re-send)

Everything else

Refer to function pydoc for more info.

Project details


Download files

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

Source Distribution

tebot-0.2.0.tar.gz (7.1 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