Skip to main content

​
Overview

Telegram tool allows you to send messages, photos, and documents via Telegram bots. The user asks to send or read messages; the agent calls Telegram and returns the outcome.

​
Installation

pip install "praisonai[tools]"

​
Environment Variables

export TELEGRAM_BOT_TOKEN=your_bot_token
export TELEGRAM_CHAT_ID=your_chat_id  # Optional default chat
Get your bot token from @BotFather.

​
Quick Start

1

Simple Usage

from praisonai_tools import TelegramTool

# Initialize
telegram = TelegramTool()

# Send message
telegram.send_message("123456789", "Hello from PraisonAI!")
2

With Configuration

Use the same tool with an agent — see Usage with Agent below, or pass env vars and options from the sections above.
Usage with Agent 
from praisonaiagents import Agent
from praisonai_tools import TelegramTool

agent = Agent(
    name="TelegramBot",
    instructions="You send notifications via Telegram.",
    tools=[TelegramTool()]
)

response = agent.chat("Send a message to chat 123456789 saying hello")
print(response)

​
Available Methods

​
send_message(chat_id, text)

Send a text message. 
from praisonai_tools import TelegramTool

telegram = TelegramTool()
telegram.send_message("123456789", "Hello!")

​
send_photo(chat_id, photo_url, caption=None)

Send a photo. 
telegram.send_photo("123456789", "https://example.com/image.jpg", "Check this out!")

​
Common Errors

ErrorCauseSolution
TELEGRAM_BOT_TOKEN not configuredMissing tokenSet environment variable
chat not foundInvalid chat IDCheck chat ID
bot was blockedUser blocked botUser must unblock
Error: API quota exceeded. Check billing.OpenAI 429 insufficient_quotaAdd credits at platform.openai.com
Error: Rate limit exceeded. Try again later.OpenAI / provider rate limitWait and retry, or upgrade plan
Error: Authentication failed. Check API key.Invalid / missing API keyVerify OPENAI_API_KEY env var
Error: Request timeout. Try again.Slow LLM / networkRetry; check connectivity

​
How It Works

​
Best Practices

Read the Telegram bot token from the environment, never hard-code it.
Confirm the target chat ID before sending so messages reach the right conversation.
Telegram throttles bursts. Retry with backoff so the agent stays responsive.

Slack

Slack messaging

Discord

Discord messaging

WhatsApp

WhatsApp messaging