Telegram API Essential Guide

What type of API does Telegram provide?

Telegram uses its own custom HTTP-based API protocol. The Telegram Bot API uses HTTPS and returns responses in JSON format. It is not a standard REST API, but has some REST-like characteristics in its design. For more advanced functionality, Telegram offers the MTProto API, which is a custom protocol developed by Telegram for accessing the full Telegram functionality. It uses a custom encryption scheme and data serialization format. Telegram's APIs are custom-designed rather than following standard API architectures like REST or GraphQL.

Does the Telegram API have webhooks?

The official Telegram Bot API supports webhooks.

Webhooks are a push mechanism where Telegram sends updates to your bot by making HTTPS POST requests to a specified URL. This eliminates the need for constant polling.

To set up a webhook:

1. Have a domain name and server with an open port (443, 80, 88, or 8443).
2. Use SSL/TLS encryption (HTTPS).
3. Have a valid SSL certificate (verified or self-signed).
4. Call the setWebhook method with your URL.

Webhook requirements:

• HTTPS is mandatory.
• Only ports 443, 80, 88, and 8443 are supported.
• A valid SSL certificate matching your domain is required.

Webhooks can receive all types of updates that a bot normally receives, including new messages, edited messages, callback queries, and inline queries. You can specify which update types to receive when setting the webhook.

Advantages of webhooks:

• Faster update delivery compared to polling.
• Reduced server load as constant checking for updates is unnecessary.

Key considerations:

• getUpdates cannot be used while a webhook is set up.
• Specific SSL/TLS version and certificate requirements apply.
• A secret token can be set for added security.

In summary, the Telegram API supports webhooks, offering a push-based mechanism for receiving bot updates. While more efficient than polling, it requires proper server setup with HTTPS support.

Rate Limits and other limitations

Here are the key points about the API rate limits for the Telegram Bot API:

General Limits

• When sending messages to a particular chat, avoid sending more than 1 message per second. Short bursts may be allowed, but eventually you'll get 429 errors if you exceed this limit consistently.

• For bulk notifications to multiple users, the API allows up to 30 messages per second overall.

• Bots can send up to 20 messages per minute to the same group.

Recommendations for Bulk Messaging

• Spread out bulk notifications over longer intervals of 8-12 hours for best results.

• The API will not allow bulk notifications to more than ~30 users per second. Exceeding this will result in 429 errors.

Per-Bot vs Per-Host Limits

• Rate limits are applied per bot account, not per host/server.

• You can create multiple bot accounts to avoid hitting rate limits if needed.

Handling Rate Limits

• If you hit rate limits, you'll receive 429 errors.

• Consider implementing retry logic with exponential backoff when receiving 429 errors.

• Use queuing mechanisms to manage requests and stay within limits.

Best Practices

• Implement proper rate limiting on your end to avoid hitting Telegram's limits.

• Use webhooks instead of long polling for more efficient updates.

• Spread out requests over time rather than sending in bursts.

• Monitor your bot's usage and adjust sending patterns if needed.

By following these limits and best practices, you can ensure your Telegram bot operates smoothly within the API's constraints. Remember to always refer to the official Telegram Bot API documentation for the most up-to-date information on rate limits.

Latest API Version

The most recent version of the Telegram Bot API is 7.1, released on May 28, 2024.

Key points to consider:

1. The Telegram Bot API is regularly updated with new features and improvements.

2. The latest update (version 7.1) introduced several new features, including:

   • Support for payments in Telegram Stars
   • New message effects
   • Ability to show captions above media
   • Support for expandable blockquote entities

3. Telegram provides a changelog that details the changes and additions in each version.

4. Developers should regularly check for updates to ensure they are using the latest features and following best practices.

5. The Bot API is separate from the main Telegram API, which is used for building custom Telegram clients.

Best practices:

1. Always refer to the official Telegram Bot API documentation for the most up-to-date information.

2. Keep your bot implementation updated to take advantage of new features and improvements.

3. Test your bot thoroughly when updating to a new API version to ensure compatibility and proper functionality.

4. Subscribe to Telegram's official channels or follow their blog to stay informed about new releases and changes.

How to get a Telegram developer account and API Keys?

Step 1: Create a Telegram Account

If you don't already have one, download the Telegram app on your mobile device and create a Telegram account.

Step 2: Request a Telegram Developer Account

1. Go to https://my.telegram.org/apps
2. Enter the phone number associated with your Telegram account (in international format)
3. You'll receive a confirmation code via SMS or in the Telegram app
4. Enter the confirmation code to sign in to your new Telegram Developer Account

Step 3: Create a New Application

1. Once signed in, select "API development tools"
2. Fill out the "Create New Application" form with your app details
3. Click "Create Application"

Step 4: Get Your API Keys

After creating the application, you'll see an "App configuration" screen that contains two important pieces of information:

• App api_id
• App api_hash

These are your API keys that you'll need to use the Telegram API.

What can you do with the Telegram API?

Here are the main data models you can interact with using the Telegram API, along with what is possible for each:

User

• Get user information (id, name, username, profile photo, etc.)
• Send messages to users
• Get user status (online/offline)
• Block/unblock users

Chat

• Get chat information (id, title, members, etc.)
• Send messages to chats
• Get chat history
• Manage chat members (add/remove/promote/demote)
• Edit chat info (title, photo, description)
• Pin/unpin messages

Message

• Send text messages, photos, videos, files, etc.
• Edit messages
• Delete messages
• Get message info (id, sender, content, etc.)
• Forward messages

File

• Upload files to Telegram servers
• Download files from Telegram
• Get file info (id, size, path, etc.)

Bot

• Create and manage bots
• Handle bot commands
• Send messages as a bot
• Answer inline queries

Sticker

• Send stickers
• Get sticker set info
• Create new sticker sets

Poll

• Create polls
• Stop polls
• Get poll results

Contact

• Send contacts
• Get contact info (phone, name, etc.)

Location

• Send locations and live locations
• Edit live locations

Inline Query Results

• Answer inline queries with various result types

Callback Query

• Handle button presses in inline keyboards

WebApp

• Launch web apps from bot messages

Payments

• Process payments

Updates

• Receive real-time updates for new messages, edits, etc.

The Telegram API provides extensive capabilities to interact with these data models for building bots and applications. The exact methods available may vary slightly between the Bot API and other client APIs like TDLib.