mirror of
https://github.com/python-telegram-bot/python-telegram-bot.git
synced 2024-10-23 17:36:26 +02:00
db6030ea83
Co-authored-by: Iulian Onofrei <5748627+revolter@users.noreply.github.com> Co-authored-by: Poolitzer <github@poolitzer.eu> Co-authored-by: Harshil <37377066+harshil21@users.noreply.github.com> Co-authored-by: Aditya <clot27@apx_managed.vanilla>
196 lines
6.8 KiB
ReStructuredText
196 lines
6.8 KiB
ReStructuredText
Examples
|
||
========
|
||
|
||
In this section we display small examples to show what a bot written with
|
||
``python-telegram-bot`` looks like.
|
||
Some bots focus on one specific
|
||
aspect of the Telegram Bot API while others focus on one of the
|
||
mechanics of this library. Except for the
|
||
:any:`examples.rawapibot` example, they all use the high-level
|
||
framework this library provides with the
|
||
:mod:`telegram.ext` submodule.
|
||
|
||
All examples are licensed under the `CC0
|
||
License <https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/LICENSE.txt>`__
|
||
and are therefore fully dedicated to the public domain. You can use them
|
||
as the base for your own bots without worrying about copyrights.
|
||
|
||
Do note that we ignore one pythonic convention. Best practice would
|
||
dictate, in many handler callbacks function signatures, to replace the
|
||
argument ``context`` with an underscore, since ``context`` is an unused
|
||
local variable in those callbacks. However, since these are examples and
|
||
not having a name for that argument confuses beginners, we decided to
|
||
have it present.
|
||
|
||
:any:`examples.echobot`
|
||
-----------------------
|
||
|
||
This is probably the base for most of the bots made with
|
||
``python-telegram-bot``. It simply replies to each text message with a
|
||
message that contains the same text.
|
||
|
||
:any:`examples.timerbot`
|
||
------------------------
|
||
|
||
This bot uses the
|
||
:class:`telegram.ext.JobQueue`
|
||
class to send timed messages. The user sets a timer by using ``/set``
|
||
command with a specific time, for example ``/set 30``. The bot then sets
|
||
up a job to send a message to that user after 30 seconds. The user can
|
||
also cancel the timer by sending ``/unset``. To learn more about the
|
||
``JobQueue``, read `this wiki article <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Extensions---JobQueue>`__.
|
||
Note: To use ``JobQueue``, you must install PTB via ``pip install "python-telegram-bot[job-queue]"``
|
||
|
||
:any:`examples.conversationbot`
|
||
-------------------------------
|
||
|
||
A common task for a bot is to ask information from the user. In v5.0 of
|
||
this library, we introduced the
|
||
:class:`telegram.ext.ConversationHandler`
|
||
for that exact purpose. This example uses it to retrieve
|
||
user-information in a conversation-like style. To get a better
|
||
understanding, take a look at the :ref:`state diagram <conversationbot-diagram>`.
|
||
|
||
:any:`examples.conversationbot2`
|
||
--------------------------------
|
||
|
||
A more complex example of a bot that uses the ``ConversationHandler``.
|
||
It is also more confusing. Good thing there is a :ref:`fancy state diagram <conversationbot2-diagram>`.
|
||
for this one, too!
|
||
|
||
:any:`examples.nestedconversationbot`
|
||
-------------------------------------
|
||
|
||
A even more complex example of a bot that uses the nested
|
||
``ConversationHandler``\ s. While it’s certainly not that complex that
|
||
you couldn’t built it without nested ``ConversationHanldler``\ s, it
|
||
gives a good impression on how to work with them. Of course, there is a
|
||
:ref:`fancy state diagram <nestedconversationbot-diagram>`
|
||
for this example, too!
|
||
|
||
:any:`examples.persistentconversationbot`
|
||
-----------------------------------------
|
||
|
||
A basic example of a bot store conversation state and user_data over
|
||
multiple restarts.
|
||
|
||
:any:`examples.inlinekeyboard`
|
||
------------------------------
|
||
|
||
This example sheds some light on inline keyboards, callback queries and
|
||
message editing. A wiki site explaining this examples lives
|
||
`here <https://github.com/python-telegram-bot/python-telegram-bot/wiki/InlineKeyboard-Example>`__.
|
||
|
||
:any:`examples.inlinekeyboard2`
|
||
-------------------------------
|
||
|
||
A more complex example about inline keyboards, callback queries and
|
||
message editing. This example showcases how an interactive menu could be
|
||
build using inline keyboards.
|
||
|
||
:any:`examples.deeplinking`
|
||
---------------------------
|
||
|
||
A basic example on how to use deeplinking with inline keyboards.
|
||
|
||
:any:`examples.inlinebot`
|
||
-------------------------
|
||
|
||
A basic example of an `inline
|
||
bot <https://core.telegram.org/bots/inline>`__. Don’t forget to enable
|
||
inline mode with `@BotFather <https://telegram.me/BotFather>`_.
|
||
|
||
:any:`examples.pollbot`
|
||
-----------------------
|
||
|
||
This example sheds some light on polls, poll answers and the
|
||
corresponding handlers.
|
||
|
||
:any:`examples.passportbot`
|
||
---------------------------
|
||
|
||
A basic example of a bot that can accept passports. Use in combination
|
||
with the :ref:`HTML page <passportbot-html>`.
|
||
Don’t forget to enable and configure payments with
|
||
`@BotFather <https://telegram.me/BotFather>`_. Check out this
|
||
`guide <https://github.com/python-telegram-bot/python-telegram-bot/wiki/Telegram-Passport>`__
|
||
on Telegram passports in PTB.
|
||
Note: To use Telegram Passport, you must install PTB via ``pip install "python-telegram-bot[passport]"``
|
||
|
||
:any:`examples.paymentbot`
|
||
--------------------------
|
||
|
||
A basic example of a bot that can accept payments. Don’t forget to
|
||
enable and configure payments with
|
||
`@BotFather <https://telegram.me/BotFather>`_.
|
||
|
||
:any:`examples.errorhandlerbot`
|
||
-------------------------------
|
||
|
||
A basic example on how to set up a custom error handler.
|
||
|
||
:any:`examples.chatmemberbot`
|
||
-----------------------------
|
||
|
||
A basic example on how ``(my_)chat_member`` updates can be used.
|
||
|
||
:any:`examples.webappbot`
|
||
-------------------------
|
||
|
||
A basic example of how `Telegram
|
||
WebApps <https://core.telegram.org/bots/webapps>`__ can be used. Use in
|
||
combination with the :ref:`HTML page <webappbot-html>`.
|
||
For your convenience, this file is hosted by the PTB team such that you
|
||
don’t need to host it yourself. Uses the
|
||
`iro.js <https://iro.js.org>`__ JavaScript library to showcase a
|
||
user interface that is hard to achieve with native Telegram
|
||
functionality.
|
||
|
||
:any:`examples.contexttypesbot`
|
||
-------------------------------
|
||
|
||
This example showcases how ``telegram.ext.ContextTypes`` can be used to
|
||
customize the ``context`` argument of handler and job callbacks.
|
||
|
||
:any:`examples.customwebhookbot`
|
||
--------------------------------
|
||
|
||
This example showcases how a custom webhook setup can be used in
|
||
combination with ``telegram.ext.Application``.
|
||
|
||
:any:`examples.arbitrarycallbackdatabot`
|
||
----------------------------------------
|
||
|
||
This example showcases how PTBs “arbitrary callback data” feature can be
|
||
used.
|
||
Note: To use arbitrary callback data, you must install PTB via ``pip install "python-telegram-bot[callback-data]"``
|
||
|
||
Pure API
|
||
--------
|
||
|
||
The :any:`examples.rawapibot` example example uses only the pure, “bare-metal” API wrapper.
|
||
|
||
.. toctree::
|
||
:hidden:
|
||
|
||
examples.arbitrarycallbackdatabot
|
||
examples.chatmemberbot
|
||
examples.contexttypesbot
|
||
examples.conversationbot
|
||
examples.conversationbot2
|
||
examples.customwebhookbot
|
||
examples.deeplinking
|
||
examples.echobot
|
||
examples.errorhandlerbot
|
||
examples.inlinebot
|
||
examples.inlinekeyboard
|
||
examples.inlinekeyboard2
|
||
examples.nestedconversationbot
|
||
examples.passportbot
|
||
examples.paymentbot
|
||
examples.persistentconversationbot
|
||
examples.pollbot
|
||
examples.rawapibot
|
||
examples.timerbot
|
||
examples.webappbot
|
||
|