Skip to content

Commit 46aeb56

Browse files
delivrancedelivrance
committed
Add AdvancedUsage.rst
1 parent 8f38ce3 commit 46aeb56

2 files changed

Lines changed: 122 additions & 0 deletions

File tree

‎docs/source/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,7 @@ To get started, press the Next button.
9393
resources/BotsInteraction
9494
resources/ErrorHandling
9595
resources/TestServers
96+
resources/AdvancedUsage
9697
resources/Changelog
9798

9899
.. toctree::

‎docs/source/resources/AdvancedUsage.rst‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
Advanced Usage
2+
==============
3+
4+
In this section, you'll be shown the alternative way of communicating with Telegram using Pyrogram: the main Telegram
5+
API with its raw functions and types.
6+
7+
Telegram Raw API
8+
----------------
9+
10+
If you can't find a high-level method for your needs or if you want complete, low-level access to the whole
11+
Telegram API, you have to use the raw :mod:`functions <pyrogram.api.functions>` and :mod:`types <pyrogram.api.types>`
12+
exposed by the ``pyrogram.api`` package and call any Telegram API method you wish using the
13+
:meth:`send() <pyrogram.Client.send>` method provided by the Client class.
14+
15+
.. hint::
16+
17+
Every available high-level method mentioned in the previous page is built on top of these raw functions.
18+
19+
Nothing stops you from using the raw functions only, but they are rather complex and `plenty of them`_ are already
20+
re-implemented by providing a much simpler and cleaner interface which is very similar to the Bot API.
21+
22+
If you think a raw function should be wrapped and added as a high-level method, feel free to ask in our Community_!
23+
24+
Caveats
25+
-------
26+
27+
As hinted before, raw functions and types can be confusing, mainly because people don't realize they must accept
28+
*exactly* the right values, but also because most of them don't have enough Python experience to fully grasp how things
29+
work.
30+
31+
This section will therefore explain some pitfalls to take into consideration when working with the raw API.
32+
33+
Chat IDs
34+
^^^^^^^^
35+
36+
The way Telegram works makes it impossible to directly send a message to a user or a chat by using their IDs only.
37+
Instead, a pair of ``id`` and ``access_hash`` wrapped in a so called ``InputPeer`` is always needed.
38+
39+
There are three different InputPeer types, one for each kind of Telegram entity.
40+
Whenever an InputPeer is needed you must pass one of these:
41+
42+
- `InputPeerUser <https://docs.pyrogram.ml/types/InputPeerUser>`_ - Users
43+
- `InputPeerChat <https://docs.pyrogram.ml/types/InputPeerChat>`_ - Basic Chats
44+
- `InputPeerChannel <https://docs.pyrogram.ml/types/InputPeerChannel>`_ - Either Channels or Supergroups
45+
46+
But you don't necessarily have to manually instantiate each object because, luckily for you, Pyrogram already provides
47+
:meth:`resolve_peer() <pyrogram.Client.resolve_peer>` as a convenience utility method that returns the correct InputPeer
48+
by accepting a peer ID only.
49+
50+
Another thing to take into consideration about chat IDs is the way they are represented: they are all integers and
51+
all positive within their respective raw types.
52+
53+
Things are different when working with Pyrogram's API because having them in the same space can theoretically lead to
54+
collisions, and that's why Pyrogram (as well as the official Bot API) uses a slightly different representation for each
55+
kind of ID.
56+
57+
For example, given the ID *123456789*, here's how Pyrogram can tell entities apart:
58+
59+
- ``+ID`` - User: *123456789*
60+
- ``-ID`` - Chat: *-123456789*
61+
- ``-100ID`` - Channel (and Supergroup): *-100123456789*
62+
63+
So, every time you take a raw ID, make sure to translate it into the correct ID when you want to use it with an
64+
high-level method.
65+
66+
Examples
67+
--------
68+
69+
- Update first name, last name and bio:
70+
71+
.. code-block:: python
72+
73+
from pyrogram import Client
74+
from pyrogram.api import functions
75+
76+
with Client("my_account") as app:
77+
app.send(
78+
functions.account.UpdateProfile(
79+
first_name="Dan", last_name="Tès",
80+
about="Bio written from Pyrogram"
81+
)
82+
)
83+
84+
- Share your Last Seen time only with your contacts:
85+
86+
.. code-block:: python
87+
88+
from pyrogram import Client
89+
from pyrogram.api import functions, types
90+
91+
with Client("my_account") as app:
92+
app.send(
93+
functions.account.SetPrivacy(
94+
key=types.InputPrivacyKeyStatusTimestamp(),
95+
rules=[types.InputPrivacyValueAllowContacts()]
96+
)
97+
)
98+
99+
- Invite users to your channel/supergroup:
100+
101+
.. code-block:: python
102+
103+
from pyrogram import Client
104+
from pyrogram.api import functions, types
105+
106+
with Client("my_account") as app:
107+
app.send(
108+
functions.channels.InviteToChannel(
109+
channel=app.resolve_peer(123456789), # ID or Username
110+
users=[ # The users you want to invite
111+
app.resolve_peer(23456789), # By ID
112+
app.resolve_peer("username"), # By username
113+
app.resolve_peer("393281234567"), # By phone number
114+
]
115+
)
116+
)
117+
118+
119+
.. _plenty of them: ../pyrogram/Client.html#messages
120+
.. _Raw Functions: Usage.html#using-raw-functions
121+
.. _Community: https://t.me/PyrogramChat

0 commit comments

Comments
 (0)