Usage¶
First you need a telegram bot and its token, visit https://core.telegram.org/bots.
After creating a bot in Telegram Platform, create at least one bot with django admin. Token is the only required field. You may need to provided public key certificate for your server. https://core.telegram.org/bots/self-signed Heroku has https and ssl by default so it is a good option if you dont want to deal with that. Add webhook url to your urlpatterns:
url(r'^telegrambot/', include('telegrambot.urls', namespace="telegrambot")
Define whe file where bot views will be defined in urlpatterns
variable, analogue to django urls
and ROOT_URLCONF
:
TELEGRAM_BOT_HANDLERS_CONF = "app.handlers"
Set bot views handlers is very easy just as defining urls in django. Module with urlpatterns
that list
different handlers:
urlpatterns = [command('start', StartView.as_command_view()),
command('author', AuthorCommandView.as_command_view()),
command('author_inverse', AuthorInverseListView.as_command_view()),
command('author_query', login_required(AuthorCommandQueryView.as_command_view())),
unknown_command(UnknownView.as_command_view()),
regex(r'author_(?P<name>\w+)', AuthorName.as_command_view()),
]
Set bot views handlers is very easy just as defining urls`in django. Module with ``bothandlers` list of different handlers command(‘command’, command_view), regex(‘re_expresion’, command_view),...:
bothandlers = [command('start', StartView.as_command_view())]
To set the webhook for telegram you need django.contrib.sites
installed, SITE_ID
configured
in settings and with it correct value in the DB. The webhook for each bot is set when a Bot is saved and
enabled
field is set to true.
Bot views responses with Telegram messages to the user with a text message and keyboard. Compound with a context and a template. The way it is handled is analogue to Django views.
Define a bot view is really easy using generic classed views, analogues to django generic views.
Simple view just with a template, image /start command just to wellcome:
class StartView(TemplateCommandView):
template_text = "bot/messages/command_start_text.txt"
List and detail views:
class AuthorListView(ListCommandView):
template_text = "bot/messages/command_author_list_text.txt"
template_keyboard = "bot/messages/command_author_list_keyboard.txt"
model = Author
context_object_name = "authors"
ordering = "-name"
class AuthorDetailView(DetailCommandView):
template_text = "bot/messages/command_author_detail_text.txt"
template_keyboard = "bot/messages/command_author_detail_keyboard.txt"
context_object_name = "author"
model = Author
slug_field = 'name'
Most common use of commands is to have /command
with no args for getting list and /command element
for
getting detail of one concrete element. It is easy to define:
class AuthorCommandView(ListDetailCommandView):
list_view_class = AuthorListView
detail_view_class = AuthorDetailView
Templates works just as normal django app. In /start command example it will search in templates dirs
for bot/messages/command_start_text.txt
to compound response message and
bot/messages/command_start_keyboard.txt
.
Authentication¶
If you require to be authenticated to perform some commands you can decorate bot_views
with login_required
. This
is the flow the user will experience until being able to execute protected command:
- If chat is not already authenticated a message with a web link will be returned to login through the web site.
- Once logged, a link to open new authenticated chat will be returned to the user with deep linking mechanism.
- The user starts this new chat and now the bot will identify this chat as authenticated until token expires.
Define in settings
the time life of a token:
TELEGRAM_BOT_TOKEN_EXPIRATION = 2 # two hours for a token to expire