# Telegram Integration via LowCodeAPI

## Overview

Telegram is a cloud-based messaging platform with bots for automated communication. The Telegram Bot API provides comprehensive functionality for:

- **Messages** - Send text, photos, videos, and other content
- **Inline Keyboards** - Create interactive buttons and menus
- **Webhooks** - Receive real-time updates from chats
- **Groups & Channels** - Manage groups and channels
- **Payments** - Accept payments within Telegram

## Base Endpoint

```
https://api.lowcodeapi.com/telegram/
```

## Authentication

LowCodeAPI handles authentication automatically using Bot API Key in the path. You only need to:

1. **Create a bot** via [BotFather](https://telegram.me/botfather) on Telegram to get your Bot API Key
2. **Connect your account** in the LowCodeAPI dashboard
3. **Use your `api_token`** in all requests

The `api_token` is your LowCodeAPI authentication token. LowCodeAPI will automatically:
- Fetch your Telegram Bot API Key
- Apply it to each request in the bot-token path parameter

**Auth Type**: Bot API Token (Path Parameter)

## API Categories

- **Social Chat** - Messaging and communication

## Common Endpoints

### Category: Message

#### Send Message

**Method**: `POST` | **LowCodeAPI Path**: `/bot-token/sendmessage`

**Full URL**:
```
https://api.lowcodeapi.com/telegram/bot-token/sendmessage?api_token={api_token}
```

**Description**: Send text messages to a chat.

**Request Body**:
```json
{
  "chat_id": "123456789",
  "text": "Hello from LowCodeAPI!",
  "parse_mode": "Markdown",
  "disable_notification": false,
  "reply_to_message_id": null
}
```

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `chat_id` | string | Yes | Unique identifier for target chat or @channelusername |
| `text` | string | Yes | Text of the message (1-4096 characters) |
| `parse_mode` | string | No | Mode for parsing entities (Markdown, MarkdownV2, HTML) |
| `entities` | array | No | List of special entities in message text |
| `disable_web_page_preview` | boolean | No | Disable link previews |
| `disable_notification` | boolean | No | Send silently |
| `reply_to_message_id` | string | No | ID of message to reply to |
| `reply_markup` | string | No | Inline keyboard or custom reply keyboard |
| `protect_content` | boolean | No | Protect content from forwarding |
| `message_effect_id` | string | No | Unique identifier of message effect |

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/telegram/bot-token/sendmessage?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "123456789",
    "text": "Hello from LowCodeAPI!",
    "parse_mode": "Markdown"
  }'
```

**Official Documentation**: [Send Message](https://core.telegram.org/bots/api#sendmessage)

---

#### Send Photo

**Method**: `POST` | **LowCodeAPI Path**: `/bot-token/sendphoto`

**Full URL**:
```
https://api.lowcodeapi.com/telegram/bot-token/sendphoto?api_token={api_token}
```

**Description**: Send photos to a chat.

**Request Body**:
```json
{
  "chat_id": "123456789",
  "photo": "https://example.com/image.jpg",
  "caption": "Check out this photo!",
  "parse_mode": "Markdown"
}
```

**Request Body Fields**:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `chat_id` | string | Yes | Unique identifier for target chat |
| `photo` | string | Yes | Photo URL or file_id |
| `caption` | string | No | Photo caption (0-1024 characters) |
| `parse_mode` | string | No | Mode for parsing caption entities |

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/telegram/bot-token/sendphoto?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "123456789",
    "photo": "https://example.com/image.jpg",
    "caption": "Check out this photo!"
  }'
```

**Official Documentation**: [Send Photo](https://core.telegram.org/bots/api#sendphoto)

---

#### Send Video

**Method**: `POST` | **LowCodeAPI Path**: `/bot-token/sendvideo`

**Full URL**:
```
https://api.lowcodeapi.com/telegram/bot-token/sendvideo?api_token={api_token}
```

**Description**: Send video files to a chat.

**Request Body**:
```json
{
  "chat_id": "123456789",
  "video": "https://example.com/video.mp4",
  "caption": "Watch this video!"
}
```

**Example Request**:
```bash
curl -X POST "https://api.lowcodeapi.com/telegram/bot-token/sendvideo?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "123456789",
    "video": "https://example.com/video.mp4",
    "caption": "Watch this video!"
  }'
```

**Official Documentation**: [Send Video](https://core.telegram.org/bots/api#sendvideo)

---

### Category: Bot Info

#### Get Me

**Method**: `GET` | **LowCodeAPI Path**: `/bot-token/getme`

**Full URL**:
```
https://api.lowcodeapi.com/telegram/bot-token/getme?api_token={api_token}
```

**Description**: Get basic information about the bot.

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/telegram/bot-token/getme?api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Get Me](https://core.telegram.org/bots/api#getme)

---

#### Get Webhook Info

**Method**: `GET` | **LowCodeAPI Path**: `/bot-token/getwebhookinfo`

**Full URL**:
```
https://api.lowcodeapi.com/telegram/bot-token/getwebhookinfo?api_token={api_token}
```

**Description**: Get current webhook status.

**Example Request**:
```bash
curl -X GET "https://api.lowcodeapi.com/telegram/bot-token/getwebhookinfo?api_token=YOUR_API_TOKEN"
```

**Official Documentation**: [Get Webhook Info](https://core.telegram.org/bots/api#getwebhookinfo)

---

## Usage Examples

### Example 1: Send Messages

Send text messages to users:

```bash
# Send a simple text message
# No ID needed in path - bot token is automatic
curl -X POST "https://api.lowcodeapi.com/telegram/bot-token/sendmessage?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "123456789",
    "text": "Hello from LowCodeAPI!"
  }'

# Send a formatted message
curl -X POST "https://api.lowcodeapi.com/telegram/bot-token/sendmessage?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "123456789",
    "text": "*Bold text* and _italic text_",
    "parse_mode": "Markdown"
  }'
```

### Example 2: Send Media

Send photos and videos:

```bash
# Send a photo
# No ID needed in path
curl -X POST "https://api.lowcodeapi.com/telegram/bot-token/sendphoto?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "123456789",
    "photo": "https://example.com/photo.jpg",
    "caption": "Here is a photo for you!"
  }'

# Send a video
# No ID needed in path
curl -X POST "https://api.lowcodeapi.com/telegram/bot-token/sendvideo?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": "123456789",
    "video": "https://example.com/video.mp4"
  }'
```

### Example 3: Bot Information

Get bot details:

```bash
# Get bot information
# No ID needed in path
curl -X GET "https://api.lowcodeapi.com/telegram/bot-token/getme?api_token=YOUR_API_TOKEN"

# Get webhook information
# No ID needed in path
curl -X GET "https://api.lowcodeapi.com/telegram/bot-token/getwebhookinfo?api_token=YOUR_API_TOKEN"
```

## Complete Endpoint Reference

For a complete list of all 68 endpoints and their parameters, refer to:

- **OpenAPI Definition**: https://backend.lowcodeapi.com/telegram/definition
- **Official Telegram Documentation**: https://core.telegram.org/bots/api

## Rate Limits & Best Practices

- **Rate Limit**: 30 messages per second to different chats, 20 per second to same chat
- **Best Practices**:
  - Store chat IDs for efficient messaging
  - Use appropriate parse_mode for formatted text
  - Implement message queueing for bulk sends
  - Use inline keyboards for interactive experiences
  - Handle errors gracefully with retry logic
  - Validate message length (max 4096 characters)
  - Use webhooks for real-time updates

## Error Handling

All responses are wrapped in a `data` key:
```json
{
  "data": {
    // Actual response from Telegram
  }
}
```

Common errors:
- **400**: Invalid request parameters or chat not found
- **403**: Bot was blocked by user
- **429**: Too many requests (rate limit exceeded)
- **500**: Telegram server error