# Telegram Bot Tool

Send messages and photos via Telegram Bot API

URL: https://agentkit.tech/docs/tools/built-in/telegram.mdx

The Telegram Bot tool enables sending messages and photos via the Telegram Bot API.

## Installation

```go
import "github.com/model-box/agent-kit/tool/telegram"
```

## Setup

### Requirements

1. **Telegram Bot**: Create a bot by messaging @BotFather on Telegram
2. **Bot Token**: Save the token provided by BotFather
3. **Chat ID**: Get the chat ID where you want to send messages

### Environment Variables

```bash
export TELEGRAM_BOT_TOKEN="your-bot-token"
```

### Getting Chat ID

1. Add your bot to a chat or channel
2. Send a message to the bot
3. Visit: `https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates`
4. Look for the `chat.id` field in the response

## Usage

```go
package main

import (
    "context"
    "os"
    
    "github.com/model-box/agent-kit/agent"
    "github.com/model-box/agent-kit/model"
    "github.com/model-box/agent-kit/session"
    "github.com/model-box/agent-kit/tool/telegram"
)

func main() {
    // Create Telegram tools
    telegramTools := telegram.NewTelegramTools()
    
    // Create model
    model := model.Model("gpt-4o").
        SetAPIKey(os.Getenv("OPENAI_API_KEY"))
    
    // Create agent with Telegram tools
    agent := agent.New().
        SetModel(model).
        SetSystemPrompt("You are a helpful assistant that can send Telegram messages.").
        AddTool(telegramTools.SendMessage()).
        AddTool(telegramTools.SendPhoto())
    
    // Create session and run
    session := session.New(agent)
    ctx := context.Background()
    
    response, err := session.Run(ctx, []agent.ChatMessage{
        agent.NewUserMessage("Send a Telegram message to chat -1001234567890 saying 'Hello!'"),
    }, nil)
    
    if err != nil {
        panic(err)
    }
    
    println(response.GetLastMessage().GetContent())
}
```

## Available Tools

### telegram\_send\_message

Send text messages with optional formatting.

| Parameter              | Type   | Required | Description                         |
| ---------------------- | ------ | -------- | ----------------------------------- |
| `chat_id`              | string | Yes      | Chat ID or username (@username)     |
| `text`                 | string | Yes      | Message text                        |
| `parse_mode`           | string | No       | "Markdown", "MarkdownV2", or "HTML" |
| `disable_notification` | bool   | No       | Send silently                       |
| `reply_to_message_id`  | int    | No       | Reply to specific message           |

### telegram\_send\_photo

Send photos with optional captions.

| Parameter              | Type   | Required | Description                     |
| ---------------------- | ------ | -------- | ------------------------------- |
| `chat_id`              | string | Yes      | Chat ID or username (@username) |
| `photo`                | string | Yes      | Photo URL                       |
| `caption`              | string | No       | Photo caption                   |
| `parse_mode`           | string | No       | Caption formatting              |
| `disable_notification` | bool   | No       | Send silently                   |

## Chat ID Formats

* **Private chats**: Positive numbers (e.g., `123456789`)
* **Groups**: Negative numbers (e.g., `-123456789`)
* **Channels**: Negative numbers starting with -100 (e.g., `-1001234567890`)
* **Usernames**: @username format for public chats

## Message Formatting

### Markdown

```
*bold text*
_italic text_
[inline URL](http://www.example.com/)
`inline code`
```

### HTML

```html
<b>bold</b>
<i>italic</i>
<a href="http://www.example.com/">inline URL</a>
<code>inline code</code>
```

## Rate Limits

* 30 messages per second to different chats
* 1 message per second to the same chat
* 20 messages per minute to the same group