0
# Update Processing
1

2
Update retrieval and processing including polling modes, webhook support, and update filtering with middleware support.
3

4
## Capabilities
5

6
### Polling Operations
7

8
Retrieve updates from Telegram servers using long polling with configurable parameters.
9

10
```python { .api }
11
def polling(self, non_stop: bool = False, skip_pending: bool = False,
12
           interval: int = 0, timeout: int = 20,
13
           long_polling_timeout: int = 20,
14
           allowed_updates: Optional[List[str]] = None):
15
    """
16
    Start polling for updates with configurable behavior.
17

18
    Parameters:
19
    - non_stop (bool): Continue polling despite API exceptions
20
    - skip_pending (bool): Skip pending updates on startup
21
    - interval (int): Delay between update retrievals
22
    - timeout (int): Request connection timeout
23
    - long_polling_timeout (int): Long polling timeout (see API docs)
24
    - allowed_updates (List[str], optional): Update types to receive
25
    """
26

27
def infinity_polling(self, timeout: int = 20, skip_pending: bool = False,
28
                    long_polling_timeout: int = 20, logger_level = logging.ERROR,
29
                    allowed_updates: Optional[List[str]] = None, **kwargs):
30
    """
31
    Infinite polling with automatic exception handling and recovery.
32

33
    Parameters:
34
    - timeout (int): Request connection timeout
35
    - skip_pending (bool): Skip old updates on start
36
    - long_polling_timeout (int): Long polling timeout
37
    - logger_level: Logging level for infinity polling
38
    - allowed_updates (List[str], optional): Update types to receive
39
    """
40

41
def get_updates(self, offset: Optional[int] = None, limit: Optional[int] = None,
42
               timeout: Optional[int] = 20, allowed_updates: Optional[List[str]] = None,
43
               long_polling_timeout: int = 20) -> List[types.Update]:
44
    """
45
    Manually retrieve updates using long polling.
46

47
    Parameters:
48
    - offset (int, optional): Identifier of first update to return
49
    - limit (int, optional): Number of updates to retrieve (1-100)
50
    - timeout (int): Request connection timeout
51
    - allowed_updates (List[str], optional): Update types to receive
52
    - long_polling_timeout (int): Timeout for long polling
53

54
    Returns:
55
    List[Update]: Array of Update objects
56
    """
57

58
def stop_polling(self):
59
    """Stop the polling process."""
60

61
def stop_bot(self):
62
    """Stop bot and clean up resources."""
63
```
64

65
### Webhook Operations
66

67
Configure webhook endpoints for receiving updates via HTTP POST requests.
68

69
```python { .api }
70
def set_webhook(self, url: Optional[str] = None, certificate = None,
71
               max_connections: Optional[int] = None, allowed_updates: Optional[List[str]] = None,
72
               ip_address: Optional[str] = None, drop_pending_updates: Optional[bool] = None,
73
               timeout: Optional[int] = None) -> bool:
74
    """
75
    Set webhook URL for receiving updates.
76

77
    Parameters:
78
    - url (str, optional): HTTPS URL for webhook (empty string removes webhook)
79
    - certificate: Public key certificate for self-signed certificates
80
    - max_connections (int, optional): Maximum simultaneous connections (1-100)
81
    - allowed_updates (List[str], optional): Update types to receive
82
    - ip_address (str, optional): Fixed IP address for webhook requests
83
    - drop_pending_updates (bool, optional): Drop all pending updates
84
    - timeout (int, optional): Request timeout
85

86
    Returns:
87
    bool: True on success
88
    """
89

90
def delete_webhook(self, drop_pending_updates: Optional[bool] = None,
91
                  timeout: Optional[int] = None) -> bool:
92
    """
93
    Remove webhook integration to switch back to getUpdates.
94

95
    Parameters:
96
    - drop_pending_updates (bool, optional): Drop all pending updates
97
    - timeout (int, optional): Request timeout
98

99
    Returns:
100
    bool: True on success
101
    """
102

103
def get_webhook_info(self, timeout: Optional[int] = None) -> types.WebhookInfo:
104
    """
105
    Get current webhook status.
106

107
    Parameters:
108
    - timeout (int, optional): Request timeout
109

110
    Returns:
111
    WebhookInfo: Current webhook configuration and status
112
    """
113
```
114

115
### Update Processing
116

117
Process individual updates and update batches with handler dispatch.
118

119
```python { .api }
120
def process_new_updates(self, updates: List[types.Update]):
121
    """
122
    Process a list of updates through registered handlers.
123

124
    Parameters:
125
    - updates (List[Update]): Updates to process
126
    """
127

128
def set_update_listener(self, listener: Callable):
129
    """
130
    Add listener for all processed updates.
131

132
    Parameters:
133
    - listener (Callable): Function to call for each update batch
134
    """
135
```
136

137
## Usage Examples
138

139
### Basic Polling
140

141
```python
142
import telebot
143

144
bot = telebot.TeleBot("YOUR_TOKEN")
145

146
@bot.message_handler(commands=['start'])
147
def start_handler(message):
148
    bot.reply_to(message, "Bot started!")
149

150
# Start polling
151
bot.polling()
152
```
153

154
### Robust Polling with Error Handling
155

156
```python
157
bot.infinity_polling(
158
    timeout=10,
159
    long_polling_timeout=5,
160
    skip_pending=True,
161
    allowed_updates=['message', 'callback_query']
162
)
163
```
164

165
### Webhook Setup
166

167
```python
168
# Set webhook
169
bot.set_webhook(
170
    url="https://yourserver.com/webhook",
171
    max_connections=5,
172
    allowed_updates=['message', 'callback_query']
173
)
174

175
# In your web server:
176
@app.route('/webhook', methods=['POST'])
177
def webhook():
178
    json_str = request.get_data().decode('UTF-8')
179
    update = telebot.types.Update.de_json(json_str)
180
    bot.process_new_updates([update])
181
    return 'OK'
182
```
183

184
### Manual Update Processing
185

186
```python
187
# Get updates manually
188
updates = bot.get_updates(timeout=30, long_polling_timeout=25)
189

190
# Process updates
191
for update in updates:
192
    bot.process_new_updates([update])
193
```
194

195
## Types
196

197
```python { .api }
198
class Update:
199
    update_id: int
200
    message: Optional[Message]
201
    edited_message: Optional[Message]
202
    channel_post: Optional[Message]
203
    edited_channel_post: Optional[Message]
204
    inline_query: Optional[InlineQuery]
205
    chosen_inline_result: Optional[ChosenInlineResult]
206
    callback_query: Optional[CallbackQuery]
207
    shipping_query: Optional[ShippingQuery]
208
    pre_checkout_query: Optional[PreCheckoutQuery]
209
    poll: Optional[Poll]
210
    poll_answer: Optional[PollAnswer]
211
    my_chat_member: Optional[ChatMemberUpdated]
212
    chat_member: Optional[ChatMemberUpdated]
213

214
class WebhookInfo:
215
    url: str
216
    has_custom_certificate: bool
217
    pending_update_count: int
218
    ip_address: Optional[str]
219
    last_error_date: Optional[int]
220
    last_error_message: Optional[str]
221
    max_connections: Optional[int]
222
    allowed_updates: Optional[List[str]]
223
```