Telegram Bot APIs

What is Telegram Bot API?

Telegram Bot API is a platform for creating automated bots that can send messages, photos, documents, and interact with users on Telegram. Perfect for notifications, alerts, and automated communication.

---

💬 Send Message - Basic

Send a simple text message to a user or group.

curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage" \
  -d "chat_id=<CHAT_ID>" \
  -d "text=Hello from DevTools!"

📝 Send Message - Markdown

Send message with Markdown formatting.

curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage" \
  -d chat_id=<CHAT_ID> \
  -d parse_mode="Markdown" \
  -d text="*Bold* _Italic_ \`Code\`"

🌐 Send Message - HTML

Send message with HTML formatting.

curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage" \
  -d chat_id=<CHAT_ID> \
  -d parse_mode="HTML" \
  -d text="<b>Bold</b> <i>Italic</i>"

📸 Send Photo - From URL

Send an image from a public URL.

curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/sendPhoto" \
  -d chat_id=<CHAT_ID> \
  -d photo="https://example.com/image.png"

🖼️ Send Photo - Local File

Upload and send a local image file.

curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/sendPhoto" \
  -F chat_id=<CHAT_ID> \
  -F photo=@"/path/to/image.png"

🏷️ Send Photo - With Caption

Send image with text caption.

curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/sendPhoto" \
  -F chat_id=<CHAT_ID> \
  -F photo=@"screenshot.png" \
  -F caption="Server status report"

📄 Send Document - Any File

Send PDF, ZIP, logs, or any file type.

curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/sendDocument" \
  -F chat_id=<CHAT_ID> \
  -F document=@"/path/to/file.pdf"

📎 Send Document - With Caption

Send file with description and timestamp.

curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/sendDocument" \
  -F chat_id=<CHAT_ID> \
  -F document=@"logs.txt" \
  -F caption="Application logs - $(date)"

🌍 Browser Request - Simple GET

Quick GET request you can use directly in browser.

https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage?chat_id=<CHAT_ID>&text=Hello

🔗 Browser Request - URL Encoded

Send message with URL encoding for special characters.

https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage?chat_id=<CHAT_ID>&text=Server%20is%20up

☕ Java - Send Text Message

Basic Java implementation using HttpURLConnection.

String token = "<YOUR_TOKEN>";
String chatId = "<CHAT_ID>";
String text = "Hello from Java!";

String url = "https://api.telegram.org/bot" + token +
             "/sendMessage?chat_id=" + chatId +
             "&text=" + URLEncoder.encode(text, "UTF-8");

HttpURLConnection conn = (HttpURLConnection) new URL(url).openConnection();
conn.setRequestMethod("GET");

int responseCode = conn.getResponseCode();
System.out.println("Response: " + responseCode);

🔷 Java - HttpClient (Java 11+)

Modern Java HttpClient implementation.

HttpClient client = HttpClient.newHttpClient();
String body = String.format(
    "chat_id=%s&text=%s",
    chatId,
    URLEncoder.encode(message, StandardCharsets.UTF_8)
);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.telegram.org/bot" + token + "/sendMessage"))
    .header("Content-Type", "application/x-www-form-urlencoded")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = client.send(request,
    HttpResponse.BodyHandlers.ofString());

📷 Java - Send Photo

Send photo using Apache HttpClient with multipart.

String token = "<YOUR_TOKEN>";
String chatId = "<CHAT_ID>";
File file = new File("image.png");

String url = "https://api.telegram.org/bot" + token + "/sendPhoto";

HttpPost post = new HttpPost(url);
MultipartEntityBuilder builder = MultipartEntityBuilder.create();

builder.addTextBody("chat_id", chatId);
builder.addBinaryBody("photo", new FileInputStream(file),
        ContentType.APPLICATION_OCTET_STREAM, file.getName());

post.setEntity(builder.build());

HttpClient client = HttpClientBuilder.create().build();
HttpResponse response = client.execute(post);
System.out.println(response.getStatusLine().getStatusCode());

🐘 PHP - Send Text Message

Send message using PHP native functions.

<?php
$token = "YOUR_TOKEN";
$chatId = "CHAT_ID";
$text = "Hello from PHP!";

$url = "https://api.telegram.org/bot{$token}/sendMessage";

$data = [
    'chat_id' => $chatId,
    'text' => $text
];

$options = [
    'http' => [
        'header'  => "Content-type: application/x-www-form-urlencoded\r\n",
        'method'  => 'POST',
        'content' => http_build_query($data)
    ]
];

$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);

echo $result;
?>

📤 PHP - Send Document

Send file using cURL in PHP.

<?php
$token = "YOUR_TOKEN";
$chatId = "CHAT_ID";
$filePath = "/path/to/file.pdf";

$url = "https://api.telegram.org/bot{$token}/sendDocument";

$post_fields = [
    'chat_id' => $chatId,
    'document' => new CURLFile($filePath)
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $post_fields);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

ℹ️ Bot Info - Get Details

Verify bot token and get bot information.

curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe

Response Example

{
  "ok": true,
  "result": {
    "id": 123456789,
    "is_bot": true,
    "first_name": "MyBot",
    "username": "my_bot"
  }
}

📥 Updates - Get Messages

Retrieve messages sent to your bot.

curl https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates

🆔 Chat ID - Find User ID

Get chat ID from updates after sending a message.

curl https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates | grep -o '"chat":{"id":[0-9]*'

🚫 Troubleshoot - 401 Unauthorized

Fix “401 Unauthorized” error (wrong token).

Solution

1. Get correct token from @BotFather
2. Verify with /getMe endpoint
3. Check for extra spaces in token

❌ Troubleshoot - 400 Chat Not Found

Fix “400 Chat not found” error.

Causes

• User hasn’t started the bot
• Wrong chat ID
• Bot not added to group

Solutions

• User must click Start button first
• Bot must be added to group (for group messages)
• Group chat IDs are negative (e.g., -987654321)

Get Correct Chat ID

# Send message to bot, then run:
curl https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates

⏱️ Troubleshoot - 429 Rate Limit

Fix “429 Too Many Requests” error.

Rate Limits

• 30 messages/second per bot
• 1 message/second per chat
• 20 requests/minute for same group

Solution

• Add delays between messages
• Use message queuing
• Batch notifications

🔐 Proxy - Java Configuration

Configure HTTP proxy in Java.

System.setProperty("http.proxyHost", "proxy.company.com");
System.setProperty("http.proxyPort", "8080");
System.setProperty("https.proxyHost", "proxy.company.com");
System.setProperty("https.proxyPort", "8080");

🌐 Proxy - cURL Configuration

Use proxy with cURL requests.

curl -x http://proxy.company.com:8080 \
  "https://api.telegram.org/bot<TOKEN>/getMe"

📚 API Methods Reference

Quick reference of common Telegram Bot API methods.

Method	Purpose
sendMessage	Send text
sendPhoto	Send image
sendDocument	Send file
sendVideo	Send video
sendAudio	Send audio
sendLocation	Send GPS coordinates
getUpdates	Get messages
getMe	Get bot info

🔑 Important Variables

Key variables for Telegram Bot API.

<YOUR_TOKEN>    → Bot token from @BotFather
<CHAT_ID>       → User ID / Group ID
Group IDs       → Always negative (-123456789)
User IDs        → Always positive (123456789)

🚀 Getting Started

Steps to create and use your first Telegram bot.

1. Message @BotFather on Telegram
2. Send /newbot command
3. Follow prompts to name your bot
4. Save the token provided
5. Start bot by sending /start from your account
6. Get chat ID using /getUpdates
7. Send your first message using API