0
# Bot Configuration and Connection
1

2
Core bot setup, connection management, and configuration options for initializing Telegram bots and managing polling or webhook connections.
3

4
## Capabilities
5

6
### TelegramBot Constructor
7

8
Creates a new Telegram bot instance with specified token and configuration options.
9

10
```javascript { .api }
11
/**
12
 * Create a new TelegramBot instance
13
 * @param {string} token - Bot authentication token from @BotFather
14
 * @param {TelegramBotOptions} [options] - Configuration options
15
 */
16
class TelegramBot extends EventEmitter {
17
  constructor(token, options);
18
}
19
```
20

21
**Usage Example:**
22

23
```javascript
24
const TelegramBot = require('node-telegram-bot-api');
25

26
// Basic bot with polling
27
const bot = new TelegramBot('YOUR_BOT_TOKEN', { polling: true });
28

29
// Bot with detailed polling configuration
30
const bot = new TelegramBot('YOUR_BOT_TOKEN', {
31
  polling: {
32
    interval: 1000,
33
    autoStart: true,
34
    params: {
35
      timeout: 10,
36
      limit: 100,
37
      allowed_updates: ['message', 'callback_query']
38
    }
39
  }
40
});
41

42
// Bot with webhook configuration
43
const bot = new TelegramBot('YOUR_BOT_TOKEN', {
44
  webHook: {
45
    port: 8443,
46
    host: '0.0.0.0',
47
    cert: './cert.pem',
48
    key: './private.key'
49
  }
50
});
51
```
52

53
### Polling Methods
54

55
Methods for managing long polling connections to receive updates from Telegram servers.
56

57
```javascript { .api }
58
/**
59
 * Start polling for updates
60
 * @param {object} [options] - Polling options
61
 * @param {boolean} [options.restart] - Whether to restart if already polling
62
 * @returns {Promise<void>}
63
 */
64
startPolling(options): Promise<void>;
65

66
/**
67
 * Stop polling for updates
68
 * @param {object} [options] - Stop options
69
 * @param {boolean} [options.cancel] - Cancel current request
70
 * @param {string} [options.reason] - Reason for stopping
71
 * @returns {Promise<void>}
72
 */
73
stopPolling(options): Promise<void>;
74

75
/**
76
 * Check if bot is currently polling
77
 * @returns {boolean} True if polling is active
78
 */
79
isPolling(): boolean;
80
```
81

82
**Usage Example:**
83

84
```javascript
85
// Start polling with options
86
await bot.startPolling({
87
  restart: true
88
});
89

90
// Check polling status
91
if (bot.isPolling()) {
92
  console.log('Bot is currently polling');
93
}
94

95
// Stop polling
96
await bot.stopPolling({
97
  cancel: true,
98
  reason: 'Server shutdown'
99
});
100
```
101

102
### Webhook Methods
103

104
Methods for managing webhook connections to receive updates via HTTP callbacks.
105

106
```javascript { .api }
107
/**
108
 * Open webhook server to receive updates
109
 * @returns {Promise<void>}
110
 */
111
openWebHook(): Promise<void>;
112

113
/**
114
 * Close webhook server
115
 * @returns {Promise<void>}
116
 */
117
closeWebHook(): Promise<void>;
118

119
/**
120
 * Check if webhook is currently open
121
 * @returns {boolean} True if webhook is open
122
 */
123
hasOpenWebHook(): boolean;
124
```
125

126
**Usage Example:**
127

128
```javascript
129
// Open webhook
130
await bot.openWebHook();
131

132
// Check webhook status
133
if (bot.hasOpenWebHook()) {
134
  console.log('Webhook is open and receiving updates');
135
}
136

137
// Close webhook
138
await bot.closeWebHook();
139
```
140

141
### Webhook Configuration
142

143
Methods for configuring webhooks on Telegram's servers.
144

145
```javascript { .api }
146
/**
147
 * Set webhook URL on Telegram servers
148
 * @param {string} url - HTTPS URL to send updates to
149
 * @param {object} [options] - Webhook options
150
 * @param {string[]} [options.allowed_updates] - List of update types to receive
151
 * @param {boolean} [options.drop_pending_updates] - Drop pending updates
152
 * @param {string} [options.secret_token] - Secret token for webhook security
153
 * @param {number} [options.max_connections] - Maximum allowed connections (1-100)
154
 * @param {object} [fileOptions] - File upload options
155
 * @returns {Promise<boolean>}
156
 */
157
setWebHook(url, options, fileOptions): Promise<boolean>;
158

159
/**
160
 * Delete webhook configuration
161
 * @param {object} [options] - Delete options
162
 * @param {boolean} [options.drop_pending_updates] - Drop pending updates
163
 * @returns {Promise<boolean>}
164
 */
165
deleteWebHook(options): Promise<boolean>;
166

167
/**
168
 * Get current webhook information
169
 * @param {object} [options] - Request options
170
 * @returns {Promise<WebhookInfo>}
171
 */
172
getWebHookInfo(options): Promise<WebhookInfo>;
173
```
174

175
**Usage Example:**
176

177
```javascript
178
// Set webhook URL
179
await bot.setWebHook('https://mybot.example.com/webhook', {
180
  allowed_updates: ['message', 'callback_query'],
181
  max_connections: 40,
182
  secret_token: 'my-secret-token'
183
});
184

185
// Get webhook info
186
const webhookInfo = await bot.getWebHookInfo();
187
console.log('Webhook URL:', webhookInfo.url);
188
console.log('Pending updates:', webhookInfo.pending_update_count);
189

190
// Delete webhook
191
await bot.deleteWebHook({
192
  drop_pending_updates: true
193
});
194
```
195

196
### Static Properties
197

198
Static properties available on the TelegramBot class.
199

200
```javascript { .api }
201
/**
202
 * Error classes used by the library
203
 * @type {object}
204
 */
205
static errors: {
206
  BaseError: class,
207
  FatalError: class,
208
  ParseError: class,
209
  TelegramError: class
210
};
211

212
/**
213
 * Supported message types
214
 * @type {string[]}
215
 */
216
static messageTypes: string[];
217
```
218

219
**Usage Example:**
220

221
```javascript
222
// Access error classes
223
const { TelegramError } = TelegramBot.errors;
224

225
try {
226
  await bot.sendMessage(chatId, message);
227
} catch (error) {
228
  if (error instanceof TelegramError) {
229
    console.error('Telegram API error:', error.code, error.message);
230
  }
231
}
232

233
// Check supported message types
234
console.log('Supported types:', TelegramBot.messageTypes);
235
// ['text', 'photo', 'video', 'audio', 'document', 'sticker', ...]
236
```
237

238
## Types
239

240
```javascript { .api }
241
interface TelegramBotOptions {
242
  polling?: boolean | {
243
    timeout?: number;           // Deprecated, use params.timeout
244
    interval?: number;          // Polling interval in milliseconds (default: 300)
245
    autoStart?: boolean;        // Start polling immediately (default: true)
246
    params?: {
247
      timeout?: number;         // Long polling timeout in seconds (default: 10)
248
      limit?: number;          // Max number of updates per request (1-100)
249
      offset?: number;         // Identifier of first update to return
250
      allowed_updates?: string[]; // Update types to receive
251
    };
252
  };
253
  webHook?: boolean | {
254
    host?: string;             // Host to bind to (default: "0.0.0.0")
255
    port?: number;            // Port to bind to (default: 8443)
256
    key?: string;             // Path to PEM private key file
257
    cert?: string;            // Path to PEM certificate file
258
    pfx?: string;             // Path to PFX certificate file
259
    autoOpen?: boolean;       // Open webhook immediately (default: true)
260
    https?: object;           // Additional HTTPS options
261
    healthEndpoint?: string;  // Health check endpoint (default: "/healthz")
262
  };
263
  onlyFirstMatch?: boolean;    // Stop after first text pattern match
264
  request?: object;           // Additional request options for all API calls
265
  baseApiUrl?: string;        // Custom API base URL (default: "https://api.telegram.org")
266
  filepath?: boolean;         // Allow file paths in media methods (default: true)
267
  badRejection?: boolean;     // Handle unhandled rejections (default: false)
268
  testEnvironment?: boolean;  // Use test environment API
269
}
270

271
interface WebhookInfo {
272
  url: string;
273
  has_custom_certificate: boolean;
274
  pending_update_count: number;
275
  ip_address?: string;
276
  last_error_date?: number;
277
  last_error_message?: string;
278
  last_synchronization_error_date?: number;
279
  max_connections?: number;
280
  allowed_updates?: string[];
281
  secret_token?: string;
282
}
283
```