telegrapy 0.1.1

Telegram Bot API

Telegrapy

Telegrapy is a package for easy building of bots using the Telegram Bot API.

---

How to start

1. Install package using pip

$ pip3 install telegrapy

ALTERNATIVE: Clone the repo

$ cd PATH_OF_YOUR_CHOICE
$ git clone https://github.com/sudogene/telegrapy.git
$ cd telegrapy

2. Test your bot's account using the following code

from telegrapy import Bot

token = 'YOUR_TOKEN'
bot = Bot(token)

print(bot.get_me())

3. Set bot to run in a loop and keep program alive

bot.run()
print('Running...')

while True:
  time.sleep(3)

When the bot runs, it indefinitely checks for message updates and handles them.

Quick example on an echo bot can be found in example.py.

---

Telegram Objects

Telegram Objects in telegrapy are object-oriented implementation of JSON-objects in the Telegram API. Each object has a unique identifier (ID) and its corresponding JSON. Hence, any object can return its own JSON format by calling the .json attribute.

User

Based on Telegram User. These are typically senders of Message.

Chat

Based on Telegram Chat. They are subclassed into PrivateChat, GroupChat, and SupergroupChat. As of now, there are not many differences in terms of parsing messages from these chat types. Chat IDs are required for bots to send messages to.

Message

Based on Telegram Message. The main bulk of data necessary for bot interactions. Contains information of the date time, sender, chat, command, and text.

---

Creating Bot Commands

Bot commands are special text/phrases recognized by bots as commands, and trigger bots to call functions defined by the user. All messages received by the bot are parsed and handled by the Handler class which is attached to the Bot upon creation. You can create your handler functions using the function signature

def function_name(msg: telegrapy.Message)

where all functions MUST take in the Message object. A code example:

def echo(msg):
  chat_id = msg.chat_id
  text = msg.text
  bot.send_message(chat_id, text)

Defined handler functions can then be added to the bot's handler:

# get the handelr
handler = bot.handler

# add the function
handler.add_command('echo', echo)

Adding of commands to the handler requires two arguments; the string command and the function.

---

Bot Methods

Not to be confused with bot commands. Bot methods are GET and POST HTTP methods based on Telegram Available Methods. As of now, the following methods have been implemented in this library:

Method	telegrapy.Bot function
getMe	get_me
sendMessage	send_message
sendPhoto	send_photo
sendAudio	send_audio
sendDocument	send_document
sendVideo	send_video
sendVoice	send_voice
sendDice	send_dice

Optional Arguments for Bot Methods

Some methods support additional arguments specific to use case. An example is reply_to_message_id which allows the bot's message to reply to a specific message. This requires the Message ID, which is conveniently available in the Message input for all handler functions.

# Direct reply to the sender's message
def echo(msg):
  chat_id = msg.chat_id
  text = msg.text
  bot.send_message(chat_id, text, reply_to_message_id=msg.id)

bot.handler.add_command('echo', echo)

... More to be added