1# AI Context from Telegram Messages
2 
3This reference is about extracting useful Telegram context for AI features.
4 
5It is not a general persistence recipe.
6 
7## Goal
8 
9When you pass Telegram data into an LLM, do not dump the raw `Message` object.
10 
11Instead, extract only the fields that change interpretation.
12 
13Good AI context is:
14- compact
15- explicit
16- structured
17- stable across message types
18 
19## The most useful signals
20 
21### 1. Visible user text
22 
23Usually the first field to extract:
24- `message.text`
25- `message.caption`
26- normalized HTML or markdown text if your bot preserves formatting
27 
28Use this as the main body of the AI input.
29 
30### 2. Quote or reply context
31 
32For modern Telegram clients, visible quoted text can arrive through `message.quote.text`.
33 
34This matters when the user is replying to something and the quote changes meaning.
35 
36Useful fields:
37- quote text
38- whether the message is a reply
39- reply target message id when available
40- thread or topic id when relevant
41 
42### 3. Poll data
43 
44Polls are useful AI context and should not be treated as empty messages.
45 
46Useful fields:
47- poll question
48- option texts
49- poll type
50- whether multiple answers are allowed
51- whether the poll is closed
52- explanation text when present
53 
54For AI formatting, keep only semantic fields, for example:
55```text
56Poll question: Which feature should we ship first?
57Options: Notifications; Calendar sync; CSV export
58Poll type: regular
59Multiple answers allowed: false
60Closed: false
61```
62 
63### 4. Sticker signals
64 
65Stickers often have little text, but they still carry meaning.
66 
67Useful fields:
68- sticker emoji
69- sticker set name if relevant to product logic
70- whether it is animated or video
71 
72For AI, pass sticker data only if it changes interpretation. In many bots, emoji alone is enough.
73 
74### 5. Attachment summary
75 
76Attachments are often important even when you do not pass the binary itself.
77 
78Useful fields by type:
79- photo: `has_photo`, caption, optional image OCR or vision output if your stack supports it
80- video: `has_video`, caption, optional transcription or vision summary
81- voice/audio: `has_voice` or `has_audio`, optional transcription
82- document: file name, mime type, caption, optional extracted text
83- animation/video note: media type plus caption or summary
84 
85For AI, prefer a summary field over raw Telegram metadata:
86```text
87Attachment: voice message
88Transcription: I need help connecting the bot to my channel.
89```
90 
91### 6. Forward origin
92 
93Forward origin can change how AI should interpret a message.
94 
95Useful fields:
96- forward origin type
97- forwarded user id or chat id when available
98- forwarded display name when available
99 
100Use `scripts/forward_origin_context.py` as a minimal typed example.
101 
102### 7. Entities and links
103 
104Entities are often more useful than raw text parsing.
105 
106Useful signals:
107- URLs
108- text links
109- mentions
110- hashtags
111- bot commands
112- custom emoji ids when your bot resolves them to text-like meanings
113 
114For AI, it is usually enough to pass a short entity summary:
115```text
116Entities: url=https://example.com, mention=@support, hashtag=#launch
117```
118 
119### 8. Sender and chat context
120 
121Sometimes meaning depends on who sent the message.
122 
123Useful fields:
124- whether sender is `from_user` or `sender_chat`
125- sender display name
126- whether the message is a channel comment
127- chat type: private, group, supergroup, channel
128- whether the chat is a forum topic
129 
130Do not pass internal ids to the model unless they affect reasoning.
131 
132## What to pass for common AI tasks
133 
134### Moderation
135 
136Useful context:
137- main text or caption
138- quote text
139- link and entity summary
140- forward origin
141- attachment type and transcription if any
142 
143### Reply intent classification
144 
145Useful context:
146- main text
147- quote text
148- reply flag
149- topic or thread flag
150 
151### Assistant response generation
152 
153Useful context:
154- main text
155- quote text
156- poll summary if the message is a poll
157- attachment summary or transcription
158- sender or chat role only if it changes tone or permissions
159 
160### Support bots
161 
162Useful context:
163- main text
164- transcription for voice notes
165- document extracted text when available
166- quote text showing what the user is responding to
167 
168## Recommended formatting for AI
169 
170Two good universal formats are:
171 
172### Option A: compact labeled text
173 
174```text
175Message text: How do I connect this?
176Quote text: Click Bot Settings and then Add to Channel.
177Chat type: supergroup
178Is reply: true
179Attachment: none
180Entities: none
181Forward origin: none
182```
183 
184This is simple and works well for prompts.
185 
186### Option B: small structured object
187 
188```json
189{
190  "message_text": "How do I connect this?",
191  "quote_text": "Click Bot Settings and then Add to Channel.",
192  "chat_type": "supergroup",
193  "is_reply": true,
194  "attachment": null,
195  "entities": []
196}
197```
198 
199This is better when a downstream service already expects structured inputs.
200 
201## What not to pass
202 
203Avoid sending large low-signal blobs such as:
204- raw serialized `Message` objects
205- every Telegram field by default
206- binary metadata that does not affect interpretation
207- internal ids that the model cannot use meaningfully
208 
209## Minimal principle
210 
211Only pass the Telegram context that changes model interpretation:
212- visible message text
213- quote text
214- poll semantics
215- attachment summary or transcription
216- forward origin metadata
217- reply or thread relation when it changes meaning
218