Skip to content

Commit ece8c95

Browse files
author
Pyrogram-Mod - Dev
committed
Add examples for Layer 224 features.
Add styled_keyboards example demonstrating KeyboardButtonStyle usage with bg_primary, bg_danger, bg_success colors and custom icons. Add star_gifts example showing how to handle StarGift service messages and filter for STAR_GIFT, STAR_GIFT_UNIQUE, NEW_CREATOR_PENDING, and CHANGE_CREATOR message types.
1 parent 4fb8de8 commit ece8c95

3 files changed

Lines changed: 238 additions & 0 deletions

File tree

‎docs/source/start/examples/index.rst‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,9 @@ to give you a basic idea.
2626
:doc:`inline_queries`, "Handle inline queries (as bot) and answer with results"
2727
:doc:`use_inline_bots`, "Query an inline bot (as user) and send a result to a chat"
2828
:doc:`bot_keyboards`, "Send normal and inline keyboards using regular bots"
29+
:doc:`styled_keyboards`, "Send keyboards with custom styles (colors, icons)"
30+
:doc:`star_gifts`, "Handle Star Gift service messages"
31+
:doc:`streaming_text`, "Stream typing updates for conversational bots"
2932
:doc:`raw_updates`, "Handle raw updates (old, should be avoided)"
3033

3134
For more advanced examples, see https://github.com/ColinShark/Pyrogram-Snippets.
@@ -43,4 +46,7 @@ For more advanced examples, see https://github.com/ColinShark/Pyrogram-Snippets.
4346
inline_queries
4447
use_inline_bots
4548
bot_keyboards
49+
styled_keyboards
50+
star_gifts
51+
streaming_text
4652
raw_updates

‎docs/source/start/examples/star_gifts.rst‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
star_gifts
2+
==========
3+
4+
This example shows how to handle Star Gift service messages.
5+
6+
Star Gifts are a Telegram feature that allows users to send gifts to each other. When a gift is received,
7+
a service message is sent with the gift details. This example demonstrates how to detect and handle these messages.
8+
9+
.. code-block:: python
10+
11+
from pyrogram import Client, filters
12+
from pyrogram.enums import MessageServiceType
13+
14+
app = Client("my_account")
15+
16+
17+
@app.on_message(filters.service)
18+
async def handle_service_messages(client, message):
19+
"""Handle service messages including star gifts."""
20+
21+
# Check if this is a star gift message
22+
if message.service == MessageServiceType.STAR_GIFT:
23+
print(f"Received a Star Gift!")
24+
print(f"Message ID: {message.id}")
25+
print(f"From: {message.from_user.first_name if message.from_user else 'Anonymous'}")
26+
print(f"Date: {message.date}")
27+
28+
# You can access the raw action for more details
29+
# The raw action contains: gift, name_hidden, saved, converted, etc.
30+
31+
elif message.service == MessageServiceType.STAR_GIFT_UNIQUE:
32+
print(f"Received a Unique/Collectible Star Gift!")
33+
print(f"Message ID: {message.id}")
34+
print(f"This is a special collectible gift that can be traded as NFT")
35+
36+
elif message.service == MessageServiceType.NEW_CREATOR_PENDING:
37+
print(f"Creator transfer is pending!")
38+
print(f"A new creator has been nominated for this channel/group")
39+
40+
elif message.service == MessageServiceType.CHANGE_CREATOR:
41+
print(f"Creator has been changed!")
42+
print(f"The ownership of this channel/group has been transferred")
43+
44+
45+
@app.on_message(filters.service)
46+
async def log_all_service_types(client, message):
47+
"""Log all service message types for debugging."""
48+
if message.service:
49+
print(f"Service message type: {message.service}")
50+
51+
52+
app.run()
53+
54+
55+
Using StarGift and StarGiftUnique Types
56+
---------------------------------------
57+
58+
The high-level ``StarGift`` and ``StarGiftUnique`` types provide easy access to gift properties:
59+
60+
.. code-block:: python
61+
62+
from pyrogram.types import StarGift, StarGiftUnique
63+
64+
# StarGift properties:
65+
# - id: Unique identifier of the gift
66+
# - sticker: Sticker representing the gift
67+
# - stars: Price in Telegram Stars
68+
# - convert_stars: Stars the receiver can convert to
69+
# - limited: Whether it's a limited-supply gift
70+
# - sold_out: Whether the gift sold out
71+
# - birthday: Whether it's a birthday-themed gift
72+
# - can_upgrade: Whether it can be upgraded to collectible
73+
# - availability_remains: Remaining gifts (for limited)
74+
# - availability_total: Total supply (for limited)
75+
76+
# StarGiftUnique properties (collectible gifts):
77+
# - id: Unique identifier
78+
# - gift_id: Base gift type ID
79+
# - title: Collectible title
80+
# - slug: For creating deep links
81+
# - num: Unique number among collectibles of same type
82+
# - burned: Whether the gift was burned
83+
# - crafted: Whether it was crafted
84+
# - owner_id: User ID of owner
85+
# - owner_address: TON blockchain address
86+
# - gift_address: NFT address on blockchain
87+
88+
89+
Filtering Star Gift Messages
90+
----------------------------
91+
92+
You can create a custom filter for star gift messages:
93+
94+
.. code-block:: python
95+
96+
from pyrogram import Client, filters
97+
from pyrogram.enums import MessageServiceType
98+
99+
# Custom filter for star gifts
100+
star_gift_filter = filters.create(
101+
lambda _, __, m: m.service in (
102+
MessageServiceType.STAR_GIFT,
103+
MessageServiceType.STAR_GIFT_UNIQUE
104+
)
105+
)
106+
107+
app = Client("my_account")
108+
109+
110+
@app.on_message(star_gift_filter)
111+
async def on_star_gift(client, message):
112+
"""Handle only star gift messages."""
113+
if message.service == MessageServiceType.STAR_GIFT:
114+
await message.reply("Thank you for the star gift! ⭐")
115+
else:
116+
await message.reply("Wow, a unique collectible gift! 🎁")
117+
118+
119+
app.run()

‎docs/source/start/examples/styled_keyboards.rst‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
styled_keyboards
2+
================
3+
4+
This example shows how to use the new KeyboardButtonStyle to create styled keyboard buttons with custom colors and icons.
5+
6+
Available since Layer 224, keyboard buttons can now have custom styles including background colors (primary, danger, success) and custom emoji icons.
7+
8+
.. code-block:: python
9+
10+
from pyrogram import Client
11+
from pyrogram.types import (
12+
ReplyKeyboardMarkup,
13+
KeyboardButton,
14+
KeyboardButtonStyle
15+
)
16+
17+
# Create a client using your bot token
18+
app = Client("my_bot", bot_token="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11")
19+
20+
21+
async def main():
22+
async with app:
23+
# Example 1: Button with primary (blue) background
24+
await app.send_message(
25+
"me", # Edit this
26+
"Styled keyboard with primary button",
27+
reply_markup=ReplyKeyboardMarkup(
28+
[[
29+
KeyboardButton(
30+
text="Primary Action",
31+
style=KeyboardButtonStyle(bg_primary=True)
32+
)
33+
]],
34+
resize_keyboard=True
35+
)
36+
)
37+
38+
# Example 2: Button with danger (red) background
39+
await app.send_message(
40+
"me", # Edit this
41+
"Styled keyboard with danger button",
42+
reply_markup=ReplyKeyboardMarkup(
43+
[[
44+
KeyboardButton(
45+
text="Delete All",
46+
style=KeyboardButtonStyle(bg_danger=True)
47+
)
48+
]],
49+
resize_keyboard=True
50+
)
51+
)
52+
53+
# Example 3: Button with success (green) background
54+
await app.send_message(
55+
"me", # Edit this
56+
"Styled keyboard with success button",
57+
reply_markup=ReplyKeyboardMarkup(
58+
[[
59+
KeyboardButton(
60+
text="Confirm",
61+
style=KeyboardButtonStyle(bg_success=True)
62+
)
63+
]],
64+
resize_keyboard=True
65+
)
66+
)
67+
68+
# Example 4: Button with custom emoji icon
69+
await app.send_message(
70+
"me", # Edit this
71+
"Styled keyboard with icon",
72+
reply_markup=ReplyKeyboardMarkup(
73+
[[
74+
KeyboardButton(
75+
text="Settings",
76+
style=KeyboardButtonStyle(
77+
icon=5368324170671202286 # Custom emoji ID
78+
)
79+
)
80+
]],
81+
resize_keyboard=True
82+
)
83+
)
84+
85+
# Example 5: Mixed styles in one keyboard
86+
await app.send_message(
87+
"me", # Edit this
88+
"Choose an action:",
89+
reply_markup=ReplyKeyboardMarkup(
90+
[
91+
[
92+
KeyboardButton(
93+
text="Save",
94+
style=KeyboardButtonStyle(bg_success=True)
95+
),
96+
KeyboardButton(
97+
text="Cancel",
98+
style=KeyboardButtonStyle(bg_danger=True)
99+
)
100+
],
101+
[
102+
KeyboardButton(
103+
text="More Options",
104+
style=KeyboardButtonStyle(bg_primary=True)
105+
)
106+
]
107+
],
108+
resize_keyboard=True
109+
)
110+
)
111+
112+
113+
app.run(main())

0 commit comments

Comments
 (0)